feat(doc,markdown,sheets,slides,wiki): emit typed error envelopes across ccm domains

Classify doc, markdown, sheets, slides, and wiki shortcut failures with typed errors so CLI users and automation receive more specific, actionable diagnostics.

Keep the migration scoped to the CCM shortcut domains, their error-contract guards, and the now-unreachable legacy save-error helper cleanup required after those domains stop calling it. Align the common-helper AST guard with latest main's migrated paths without reintroducing shortcuts removed upstream.

.golangci.yml

@@ -73,20 +73,20 @@ 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/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
+      - 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/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/)
         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/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/|shortcuts/common/mcp_client\.go)
         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/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/contact/|shortcuts/doc/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/markdown/|shortcuts/minutes/|shortcuts/okr/|shortcuts/sheets/|shortcuts/slides/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/wiki/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.49] - 2026-06-08
+
+### Features
+
+- **events**: Add whiteboard event domain with per-board subscription (#1265)
+- **im**: Support feed group (#1102)
+- **im**: Add feed shortcut create, list, and remove shortcuts (#1273)
+- **im**: Format feed group error handling (#1308)
+- **im**: Return typed error envelopes across the im domain (#1230)
+- **base**: Emit typed error envelopes across the base domain (#1248)
+- **calendar**: Emit typed error envelopes across the calendar domain (#1232)
+- **task**: Emit typed error envelopes across the task domain (#1231)
+- **okr,whiteboard**: Emit typed error envelopes across both domains (#1236)
+- **minutes,vc**: Emit typed error envelopes across both domains (#1234)
+- **markdown**: Harden create upload failures (#1325)
+- **drive**: Harden inspect shortcut failures (#1324)
+- **slides**: Add IconPark lookup for Lark slides (#1123)
+- **doc**: Remove docs v1 API (#1291)
+- **cli**: Add `skills` command to read embedded skill content (#1318)
+- **cli**: Fetch official skills index (#1301)
+- **shared**: Document relative-path-only file arguments (#1319)
+- **scopes**: Clear `recommend.allow` scope auto-approve overrides (#1272)
+- **shortcuts**: Check shortcut example commands against the live CLI tree (#1244)
+
+### Bug Fixes
+
+- **events**: Keep bounded event consume runs alive after stdin EOF (#1285)
+- **drive**: Use docs secure label read scope (#1281)
+
+### Documentation
+
+- **approval**: Restructure skill with intent table and scope boundaries (#1307)
+- **skills**: Tighten drive and markdown guardrails (#1326)
+- **skills**: Optimize calendar, vc, and minutes skill guidance (#1269)
+- **markdown**: Add markdown domain template (#1293)
+- **markdown**: Improve lark-markdown skill guidance (#1279)
+- **doc**: Improve lark-doc skill guidance (#1283)
+- **wiki**: Optimize skill guidance and routing boundaries (#1275)
+- **slides**: Tighten routing/boundary and reconcile in-slide whiteboard (#1169)
+
 ## [v1.0.48] - 2026-06-04
 
 ### Features
@@ -1026,6 +1066,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.49]: https://github.com/larksuite/cli/releases/tag/v1.0.49
 [v1.0.48]: https://github.com/larksuite/cli/releases/tag/v1.0.48
 [v1.0.47]: https://github.com/larksuite/cli/releases/tag/v1.0.47
 [v1.0.46]: https://github.com/larksuite/cli/releases/tag/v1.0.46

cmd/auth/login.go

@@ -296,10 +296,11 @@ func authLoginRun(opts *LoginOptions) error {
 	}
 
 	// Step 2: Show user code and verification URL.
-	// Both branches surface AgentTimeoutHint, but on different channels:
-	// JSON mode embeds it as a structured field (so an agent that captures
-	// stdout into a JSON parser sees it without stream-mixing surprises),
-	// text mode prints to stderr (alongside the URL prompt).
+	// JSON mode embeds AgentTimeoutHint as a structured field so agents that
+	// capture stdout into a JSON parser see it without stream-mixing surprises.
+	// Text mode prints the hint to stderr only when running under a non-TTY
+	// (i.e. piped / agent harness), since humans reading a terminal don't need
+	// the agent-oriented instructions.
 	if opts.JSON {
 		data := map[string]interface{}{
 			"event":                     "device_authorization",
@@ -317,7 +318,9 @@ func authLoginRun(opts *LoginOptions) error {
 	} else {
 		fmt.Fprintf(f.IOStreams.ErrOut, msg.OpenURL)
 		fmt.Fprintf(f.IOStreams.ErrOut, "  %s\n\n", authResp.VerificationUriComplete)
-		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
+		if f.IOStreams != nil && !f.IOStreams.IsTerminal {
+			fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
+		}
 	}
 
 	// Step 3: Poll for token
@@ -404,10 +407,11 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 			fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] auth login: failed to remove cached requested scopes: %v\n", err)
 		}
 	}
-	// Skip the stderr hint in JSON mode — the --no-wait call that issued the
-	// device_code already returned the hint as a JSON field, and writing
-	// text to stderr would pollute consumers that combine streams via 2>&1.
-	if !opts.JSON {
+	// Skip the stderr hint in JSON mode (the --no-wait call that issued
+	// the device_code already surfaced it as a JSON field), and also skip it
+	// when running on an interactive terminal — the agent-oriented
+	// instructions only matter for piped / harness environments.
+	if !opts.JSON && f.IOStreams != nil && !f.IOStreams.IsTerminal {
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)

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/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/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/update/update_test.go

@@ -49,12 +49,21 @@ 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{}
@@ -478,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
@@ -810,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")
@@ -862,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")
@@ -1006,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...)
@@ -1044,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,
@@ -1088,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,
@@ -1147,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...)
@@ -1196,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...)

internal/cmdutil/factory.go

@@ -6,6 +6,7 @@ package cmdutil
 import (
 	"context"
 	"io"
+	"io/fs"
 	"net/http"
 	"strings"
 
@@ -43,6 +44,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.

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/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 {

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"
 )
@@ -232,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

@@ -80,6 +80,30 @@ func ParseGlobalSkillsJSON(text string) []string {
 	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{}
@@ -160,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
 				}
 			}
@@ -223,6 +246,7 @@ func PlanSync(input SyncInput) SyncPlan {
 }
 
 type SkillsRunner interface {
+	ListOfficialSkillsIndex() *selfupdate.NpmResult
 	ListOfficialSkills() *selfupdate.NpmResult
 	ListGlobalSkillsJSON() *selfupdate.NpmResult
 	ListGlobalSkills() *selfupdate.NpmResult
@@ -258,14 +282,9 @@ 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 ---
@@ -327,6 +346,40 @@ 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 {

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
 
@@ -110,6 +123,43 @@ func TestParseGlobalSkillsJSONInvalidOrUnsupported(t *testing.T) {
 	}
 }
 
+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{
@@ -156,9 +206,11 @@ func TestPlanForceRestoresAllOfficial(t *testing.T) {
 }
 
 type fakeSkillsRunner struct {
+	officialIndexOut string
 	officialOut      string
 	globalJSONOut    string
 	globalOut        string
+	officialIndexErr error
 	officialErr      error
 	globalJSONErr    error
 	globalErr        error
@@ -166,6 +218,8 @@ type fakeSkillsRunner struct {
 	installAllErr    error
 	installed        [][]string
 	installedAll     int
+	listedIndex      int
+	listedOfficial   int
 	listedGlobalJSON int
 	listedGlobalText int
 }
@@ -181,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")
@@ -206,7 +273,16 @@ func globalSkillsJSONOutput(names ...string) string {
 	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
@@ -255,9 +331,10 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
-		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-custom"),
-		globalOut:     globalSkillsOutput("lark-mail"),
+		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",
@@ -289,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})
@@ -322,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})
@@ -342,9 +527,10 @@ func TestSyncSkills_GlobalJSONFailureFallsBackToTextList(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONErr: fmt.Errorf("json list failed"),
-		globalOut:     globalSkillsOutput("lark-calendar"),
+		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})
@@ -367,9 +553,10 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		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"),
+		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})
@@ -391,9 +578,10 @@ func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut: `[]`,
-		globalOut:     "Some unrecognized output format\n",
+		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})
@@ -420,9 +608,10 @@ func TestSyncSkills_EmptyToUpdateFallsBackToFullInstall(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:     globalSkillsOutput(),
-		installAllErr: nil,
+		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})
@@ -445,11 +634,12 @@ func TestSyncSkills_InstallFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		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,
+		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})
@@ -477,11 +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"),
-		globalJSONOut: globalSkillsJSONOutput("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})
@@ -510,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})
@@ -527,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})
@@ -551,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})
@@ -576,11 +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"),
-		globalJSONOut: globalSkillsJSONOutput("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})
@@ -601,11 +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"),
-		globalJSONOut: globalSkillsJSONOutput("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})
@@ -625,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})
@@ -643,9 +840,10 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	}
 
 	runner2 := &fakeSkillsRunner{
-		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut: globalSkillsJSONOutput("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" {

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -17,11 +17,20 @@ import (
 var migratedCommonHelperPaths = []string{
 	"shortcuts/base/",
 	"shortcuts/calendar/",
+	"shortcuts/contact/",
+	"shortcuts/doc/",
 	"shortcuts/drive/",
+	"shortcuts/im/",
 	"shortcuts/mail/",
+	"shortcuts/markdown/",
+	"shortcuts/minutes/",
 	"shortcuts/okr/",
+	"shortcuts/sheets/",
+	"shortcuts/slides/",
 	"shortcuts/task/",
+	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
+	"shortcuts/wiki/",
 }
 
 const commonImportPath = "github.com/larksuite/cli/shortcuts/common"

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -18,12 +18,20 @@ import (
 var migratedEnvelopePaths = []string{
 	"shortcuts/base/",
 	"shortcuts/calendar/",
+	"shortcuts/contact/",
+	"shortcuts/doc/",
 	"shortcuts/drive/",
-	"shortcuts/mail/",
-	"shortcuts/okr/",
-	"shortcuts/task/",
-	"shortcuts/whiteboard/",
 	"shortcuts/im/",
+	"shortcuts/mail/",
+	"shortcuts/markdown/",
+	"shortcuts/minutes/",
+	"shortcuts/okr/",
+	"shortcuts/sheets/",
+	"shortcuts/slides/",
+	"shortcuts/task/",
+	"shortcuts/vc/",
+	"shortcuts/whiteboard/",
+	"shortcuts/wiki/",
 }
 
 // legacyOutputImportPath is the import path of the package that declares the

lint/errscontract/rules_test.go

@@ -691,7 +691,7 @@ func boom() error {
 	return &output.ExitError{Code: 1}
 }
 `
-	v := CheckNoLegacyEnvelopeLiteral("shortcuts/contact/foo.go", src)
+	v := CheckNoLegacyEnvelopeLiteral("shortcuts/unmigrated/foo.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path should pass, got: %+v", v)
 	}
@@ -907,7 +907,7 @@ func boom(runtime *common.RuntimeContext) error {
 	return err
 }
 `
-	v := CheckNoLegacyRuntimeAPICall("shortcuts/contact/contact_get.go", src)
+	v := CheckNoLegacyRuntimeAPICall("shortcuts/unmigrated/sample.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must not fire, got: %+v", v)
 	}
@@ -944,11 +944,19 @@ func TestCheckNoLegacyCommonHelperCall_RejectsLegacyHelpersOnMigratedPath(t *tes
 		"HandleApiResult",
 	}
 	paths := []string{
+		"shortcuts/calendar/calendar_create.go",
+		"shortcuts/contact/contact_search_user.go",
+		"shortcuts/doc/docs_fetch_v2.go",
 		"shortcuts/drive/drive_search.go",
+		"shortcuts/im/im_messages_send.go",
 		"shortcuts/mail/mail_send.go",
+		"shortcuts/markdown/markdown_fetch.go",
 		"shortcuts/okr/okr_progress_create.go",
+		"shortcuts/sheets/helpers.go",
+		"shortcuts/slides/slides_create.go",
 		"shortcuts/task/task_update.go",
 		"shortcuts/whiteboard/whiteboard_query.go",
+		"shortcuts/wiki/wiki_node_get.go",
 	}
 	for _, path := range paths {
 		for _, helper := range helpers {
@@ -997,6 +1005,34 @@ func boom() {
 	}
 }
 
+func TestCheckNoLegacyCommonHelperCall_CoversCCMPathsWithAliasAndFunctionValue(t *testing.T) {
+	paths := []string{
+		"shortcuts/doc/docs_fetch_v2.go",
+		"shortcuts/markdown/markdown_fetch.go",
+		"shortcuts/sheets/helpers.go",
+		"shortcuts/slides/slides_create.go",
+		"shortcuts/wiki/wiki_node_get.go",
+	}
+	src := `package migrated
+
+import c "github.com/larksuite/cli/shortcuts/common"
+
+func boom() {
+	f := c.FlagErrorf
+	_ = f
+	c.WrapInputStatError(nil)
+}
+`
+	for _, path := range paths {
+		t.Run(path, func(t *testing.T) {
+			v := CheckNoLegacyCommonHelperCall(path, src)
+			if len(v) != 2 {
+				t.Fatalf("expected 2 violations for aliased/function-value legacy helpers on %s, got %d: %+v", path, len(v), v)
+			}
+		})
+	}
+}
+
 func TestCheckNoLegacyCommonHelperCall_AllowsNonMigratedPath(t *testing.T) {
 	src := `package contact
 
@@ -1006,7 +1042,7 @@ func boom() {
 	common.FlagErrorf("legacy allowed until domain migrates")
 }
 `
-	v := CheckNoLegacyCommonHelperCall("shortcuts/contact/contact_get.go", src)
+	v := CheckNoLegacyCommonHelperCall("shortcuts/unmigrated/sample.go", src)
 	if len(v) != 0 {
 		t.Errorf("non-migrated path must pass, got: %+v", v)
 	}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.48",
+  "version": "1.0.49",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

shortcuts/common/drive_meta.go

@@ -23,7 +23,7 @@ func FetchDriveMeta(runtime *RuntimeContext, token, docType string, withURL bool
 		body["with_url"] = true
 	}
 
-	data, err := runtime.CallAPI(
+	data, err := runtime.CallAPITyped(
 		"POST",
 		"/open-apis/drive/v1/metas/batch_query",
 		nil,

shortcuts/common/drive_meta_test.go

@@ -10,6 +10,7 @@ import (
 	"sync/atomic"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -103,6 +104,13 @@ func TestFetchDriveMetaTitle(t *testing.T) {
 		if err == nil {
 			t.Fatal("FetchDriveMetaTitle() expected error, got nil")
 		}
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed error, got %T", err)
+		}
+		if p.Code != 99991668 {
+			t.Fatalf("code = %d, want 99991668", p.Code)
+		}
 	})
 }
 

shortcuts/common/runner.go

@@ -676,30 +676,10 @@ func WrapInputStatErrorTyped(err error, readMsg ...string) error {
 		WithCause(err)
 }
 
-// WrapSaveErrorByCategory maps a FileIO.Save error to structured output errors,
-// using standardized messages and the given error category (e.g. "api_error", "io").
-// Path validation errors always use ErrValidation (exit code 2).
-//
-// Deprecated: use WrapSaveErrorTyped for typed error envelopes.
-func WrapSaveErrorByCategory(err error, category string) error {
-	if err == nil {
-		return nil
-	}
-	var me *fileio.MkdirError
-	switch {
-	case errors.Is(err, fileio.ErrPathValidation):
-		return output.ErrValidation("unsafe output path: %s", err)
-	case errors.As(err, &me):
-		return output.Errorf(output.ExitInternal, category, "cannot create parent directory: %s", err)
-	default:
-		return output.Errorf(output.ExitInternal, category, "cannot create file: %s", err)
-	}
-}
-
 // WrapSaveErrorTyped maps a FileIO.Save error to typed validation/internal errors.
-// Unlike WrapSaveErrorByCategory, non-path failures always emit the canonical
-// "internal" wire type: call sites migrating from a custom category
-// (e.g. "io", "api_error") change their envelope's type field.
+// Non-path failures always emit the canonical "internal" wire type: call sites
+// migrating from a custom legacy category (e.g. "io", "api_error") change
+// their envelope's type field.
 func WrapSaveErrorTyped(err error) error {
 	if err == nil {
 		return nil

shortcuts/common/userids.go

@@ -6,24 +6,8 @@ package common
 import (
 	"fmt"
 	"strings"
-
-	"github.com/larksuite/cli/internal/output"
 )
 
-// ResolveOpenIDs expands the special identifier "me" to the current user's
-// open_id, removes duplicates case-insensitively while preserving the
-// first-occurrence form, and returns nil for an empty input. flagName is
-// used in error messages to point the user at the offending CLI flag.
-//
-// Deprecated: use ResolveOpenIDsTyped for typed error envelopes.
-func ResolveOpenIDs(flagName string, ids []string, runtime *RuntimeContext) ([]string, error) {
-	out, msg := resolveOpenIDs(flagName, ids, runtime)
-	if msg != "" {
-		return nil, output.ErrValidation("%s", msg)
-	}
-	return out, nil
-}
-
 // ResolveOpenIDsTyped expands the special identifier "me" to the current
 // user's open_id, removes duplicates case-insensitively while preserving the
 // first-occurrence form, and returns nil for an empty input. flagName names

shortcuts/common/userids_test.go

@@ -17,9 +17,9 @@ func resolveOpenIDsTestRuntime(userOpenID string) *RuntimeContext {
 	return TestNewRuntimeContext(cmd, cfg)
 }
 
-func TestResolveOpenIDs_Empty(t *testing.T) {
+func TestResolveOpenIDsTyped_Empty(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
-	out, err := ResolveOpenIDs("--user-ids", nil, rt)
+	out, err := ResolveOpenIDsTyped("--user-ids", nil, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -28,21 +28,9 @@ func TestResolveOpenIDs_Empty(t *testing.T) {
 	}
 }
 
-func TestResolveOpenIDs_ExpandsMeAndDedups(t *testing.T) {
+func TestResolveOpenIDsTyped_MeIsCaseInsensitive(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
-	out, err := ResolveOpenIDs("--user-ids", []string{"me", "ou_a", "me", "ou_a"}, rt)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	want := []string{"ou_self", "ou_a"}
-	if len(out) != len(want) || out[0] != want[0] || out[1] != want[1] {
-		t.Fatalf("got %v, want %v", out, want)
-	}
-}
-
-func TestResolveOpenIDs_MeIsCaseInsensitive(t *testing.T) {
-	rt := resolveOpenIDsTestRuntime("ou_self")
-	out, err := ResolveOpenIDs("--user-ids", []string{"ou_other", "me", "Me", "ME"}, rt)
+	out, err := ResolveOpenIDsTyped("--user-ids", []string{"ou_other", "me", "Me", "ME"}, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
@@ -52,22 +40,11 @@ func TestResolveOpenIDs_MeIsCaseInsensitive(t *testing.T) {
 	}
 }
 
-func TestResolveOpenIDs_MeWithoutLogin(t *testing.T) {
-	rt := resolveOpenIDsTestRuntime("")
-	_, err := ResolveOpenIDs("--user-ids", []string{"me"}, rt)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "--user-ids") {
-		t.Fatalf("error should mention the offending flag name; got: %v", err)
-	}
-}
-
-func TestResolveOpenIDs_DedupIsCaseInsensitive(t *testing.T) {
+func TestResolveOpenIDsTyped_DedupIsCaseInsensitive(t *testing.T) {
 	rt := resolveOpenIDsTestRuntime("ou_self")
 	// Same underlying open_id with three case variants — should collapse to
 	// one entry, preserving the first-occurrence form.
-	out, err := ResolveOpenIDs("--user-ids", []string{"ou_abc123", "OU_ABC123", "Ou_Abc123"}, rt)
+	out, err := ResolveOpenIDsTyped("--user-ids", []string{"ou_abc123", "OU_ABC123", "Ou_Abc123"}, rt)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}

shortcuts/common/validate.go

@@ -106,25 +106,6 @@ func ExactlyOneTyped(rt *RuntimeContext, flags ...string) error {
 	return MutuallyExclusiveTyped(rt, flags...)
 }
 
-// ValidatePageSize validates that the named flag (if set) is an integer within [minVal, maxVal].
-// It returns the parsed value (or defaultVal if the flag is empty) and any validation error.
-//
-// Deprecated: use ValidatePageSizeTyped for typed error envelopes.
-func ValidatePageSize(rt *RuntimeContext, flagName string, defaultVal, minVal, maxVal int) (int, error) {
-	s := rt.Str(flagName)
-	if s == "" {
-		return defaultVal, nil
-	}
-	n, err := strconv.Atoi(s)
-	if err != nil {
-		return 0, FlagErrorf("invalid --%s %q: must be an integer", flagName, s)
-	}
-	if n < minVal || n > maxVal {
-		return 0, FlagErrorf("invalid --%s %d: must be between %d and %d", flagName, n, minVal, maxVal)
-	}
-	return n, nil
-}
-
 // ValidatePageSizeTyped validates that the named flag (if set) is an integer within [minVal, maxVal].
 // It returns the parsed value (or defaultVal if the flag is empty) and any validation error.
 func ValidatePageSizeTyped(rt *RuntimeContext, flagName string, defaultVal, minVal, maxVal int) (int, error) {

shortcuts/common/validate_ids.go

@@ -5,8 +5,6 @@ package common
 
 import (
 	"strings"
-
-	"github.com/larksuite/cli/internal/output"
 )
 
 // ValidateChatIDTyped checks if a chat ID has valid format (oc_ prefix).
@@ -42,17 +40,6 @@ func normalizeChatID(input string) (string, string) {
 	return input, ""
 }
 
-// ValidateUserID checks if a user ID has valid format (ou_ prefix).
-//
-// Deprecated: use ValidateUserIDTyped for typed error envelopes.
-func ValidateUserID(input string) (string, error) {
-	userID, msg := normalizeUserID(input)
-	if msg != "" {
-		return "", output.ErrValidation("%s", msg)
-	}
-	return userID, nil
-}
-
 // ValidateUserIDTyped checks if a user ID has valid format (ou_ prefix).
 // param names the flag being validated (e.g. "--creator-ids") and is
 // recorded on the typed error.

shortcuts/contact/contact_errors.go

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+)
+
+const contactFanoutRetryHint = "retry the command; if it persists, narrow --queries to a single term to isolate the failing input"
+
+func contactInvalidResponseError(format string, args ...any) *errs.InternalError {
+	return errs.NewInternalError(errs.SubtypeInvalidResponse, format, args...)
+}
+
+func contactFanoutErrorSummary(err error) string {
+	if p, ok := errs.ProblemOf(err); ok {
+		if p.Code >= 100 && p.Code < 600 {
+			prefix := fmt.Sprintf("HTTP %d:", p.Code)
+			body := strings.TrimSpace(strings.TrimPrefix(p.Message, prefix))
+			msg := fmt.Sprintf("HTTP %d %s", p.Code, http.StatusText(p.Code))
+			if body != "" {
+				msg = fmt.Sprintf("%s: %s", msg, contactTruncateError(body, 200))
+			}
+			return msg
+		}
+		if p.Code != 0 {
+			return fmt.Sprintf("API %d: %s", p.Code, p.Message)
+		}
+		return p.Message
+	}
+	return err.Error()
+}
+
+// contactFanoutAllFailedError builds the top-level error returned when every
+// fanout query fails. It mirrors the representative (first) failure's
+// classification — category, subtype, code, log_id, retryable, hint — so the
+// exit-code classifier still sees the real signal, while carrying the aggregate
+// message. The representative error is copied (never mutated) and kept as the
+// cause, so a single-query problem object is not rewritten into an aggregate one.
+func contactFanoutAllFailedError(err error, msg string) error {
+	var (
+		apiErr *errs.APIError
+		netErr *errs.NetworkError
+		intErr *errs.InternalError
+	)
+	switch {
+	case errors.As(err, &apiErr):
+		c := *apiErr
+		c.Message = msg
+		c.Cause = err
+		return &c
+	case errors.As(err, &netErr):
+		c := *netErr
+		c.Message = msg
+		c.Cause = err
+		return &c
+	case errors.As(err, &intErr):
+		c := *intErr
+		c.Message = msg
+		c.Cause = err
+		return &c
+	}
+	return errs.NewInternalError(errs.SubtypeUnknown, "%s", msg).WithHint(contactFanoutRetryHint).WithCause(err)
+}
+
+func contactTruncateError(s string, maxRunes int) string {
+	r := []rune(s)
+	if len(r) <= maxRunes {
+		return s
+	}
+	return string(r[:maxRunes]) + "..."
+}

shortcuts/contact/contact_errors_test.go

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestContactFanoutErrorSummary_HTTPStatus(t *testing.T) {
+	err := errs.NewNetworkError(errs.SubtypeNetworkServer, `HTTP 503: {"reason":"upstream_unavailable"}`).
+		WithCode(503).
+		WithRetryable()
+
+	got := contactFanoutErrorSummary(err)
+	if !strings.HasPrefix(got, "HTTP 503 Service Unavailable: ") {
+		t.Fatalf("summary: got %q", got)
+	}
+	if !strings.Contains(got, "upstream_unavailable") {
+		t.Fatalf("summary should include truncated body details, got %q", got)
+	}
+}
+
+func TestContactInvalidResponseError_TypedInternal(t *testing.T) {
+	got := contactInvalidResponseError("decode contact response failed")
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", got)
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
+	}
+}
+
+func TestContactFanoutAllFailedError_PreservesTypedProblem(t *testing.T) {
+	err := errs.NewAPIError(errs.SubtypeRateLimit, "rate limit").
+		WithCode(99991663).
+		WithLogID("log-contact-1").
+		WithRetryable()
+
+	got := contactFanoutAllFailedError(err, "all 2 queries failed; first: API 99991663: rate limit (query=\"alice\")")
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", got)
+	}
+	if p.Category != errs.CategoryAPI || p.Subtype != errs.SubtypeRateLimit {
+		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
+	}
+	if p.Code != 99991663 || p.LogID != "log-contact-1" || !p.Retryable {
+		t.Fatalf("problem metadata not preserved: %+v", p)
+	}
+	if !strings.Contains(p.Message, "all 2 queries failed") {
+		t.Fatalf("problem message not decorated: %q", p.Message)
+	}
+	// The representative error must not be mutated: it stays a single-query
+	// failure, while the aggregate is a distinct value carrying it as cause.
+	if err.Message != "rate limit" {
+		t.Fatalf("representative error message was mutated: %q", err.Message)
+	}
+	if !errors.Is(got, err) {
+		t.Fatalf("aggregate error should keep the representative failure as its cause")
+	}
+}
+
+func TestContactFanoutAllFailedError_UntypedGetsActionableHint(t *testing.T) {
+	got := contactFanoutAllFailedError(nil, "all 2 queries failed; first: internal error (query=\"alice\")")
+	p, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", got)
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
+	}
+	if !strings.Contains(p.Hint, "narrow --queries") {
+		t.Fatalf("hint should guide recovery, got %q", p.Hint)
+	}
+}

shortcuts/contact/contact_get_user.go

@@ -28,7 +28,8 @@ var ContactGetUser = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if runtime.Str("user-id") == "" && runtime.IsBot() {
-			return common.FlagErrorf("bot identity cannot get current user info, specify --user-id")
+			return common.ValidationErrorf("bot identity cannot get current user info, specify --user-id").
+				WithParam("--user-id")
 		}
 		return nil
 	},
@@ -63,7 +64,7 @@ var ContactGetUser = common.Shortcut{
 
 		if userId == "" {
 			// Current user
-			data, err := runtime.CallAPI("GET", "/open-apis/authen/v1/user_info", nil, nil)
+			data, err := runtime.CallAPITyped("GET", "/open-apis/authen/v1/user_info", nil, nil)
 			if err != nil {
 				return err
 			}
@@ -87,7 +88,7 @@ var ContactGetUser = common.Shortcut{
 
 		if runtime.IsBot() {
 			// Bot identity: GET /contact/v3/users/:user_id (full profile)
-			data, err := runtime.CallAPI("GET", "/open-apis/contact/v3/users/"+url.PathEscape(userId),
+			data, err := runtime.CallAPITyped("GET", "/open-apis/contact/v3/users/"+url.PathEscape(userId),
 				map[string]interface{}{"user_id_type": userIdType}, nil)
 			if err != nil {
 				return err
@@ -110,7 +111,7 @@ var ContactGetUser = common.Shortcut{
 		}
 
 		// User identity: POST /contact/v3/users/basic_batch (lightweight)
-		data, err := runtime.CallAPI("POST", "/open-apis/contact/v3/users/basic_batch",
+		data, err := runtime.CallAPITyped("POST", "/open-apis/contact/v3/users/basic_batch",
 			map[string]interface{}{"user_id_type": userIdType},
 			map[string]interface{}{"user_ids": []string{userId}})
 		if err != nil {

shortcuts/contact/contact_get_user_test.go

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"bytes"
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestGetUser_BotCurrentUserValidationTyped(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, searchUserDefaultConfig())
+
+	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--as", "bot"}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected validation error")
+	}
+	var validation *errs.ValidationError
+	if !errors.As(err, &validation) {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	if validation.Param != "--user-id" {
+		t.Fatalf("param: got %q, want --user-id", validation.Param)
+	}
+}
+
+func TestGetUser_DryRunShapes(t *testing.T) {
+	cases := []struct {
+		name string
+		args []string
+		want []string
+	}{
+		{
+			name: "current user",
+			args: []string{"+get-user", "--dry-run", "--as", "user"},
+			want: []string{"GET", "/authen/v1/user_info", "current_user"},
+		},
+		{
+			name: "bot specific user",
+			args: []string{"+get-user", "--user-id", "ou_a", "--dry-run", "--as", "bot"},
+			want: []string{"GET", "/contact/v3/users/ou_a", "ou_a", "open_id"},
+		},
+		{
+			name: "user basic batch",
+			args: []string{"+get-user", "--user-id", "ou_a", "--dry-run", "--as", "user"},
+			want: []string{"POST", "/contact/v3/users/basic_batch", "ou_a", "open_id"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, stdout, _, _ := cmdutil.TestFactory(t, searchUserDefaultConfig())
+			if err := mountAndRun(t, ContactGetUser, tc.args, f, stdout); err != nil {
+				t.Fatalf("dry-run: %v", err)
+			}
+			out := stdout.String()
+			for _, want := range tc.want {
+				if !bytes.Contains(stdout.Bytes(), []byte(want)) {
+					t.Fatalf("dry-run output missing %q: %s", want, out)
+				}
+			}
+		})
+	}
+}
+
+func TestGetUser_CurrentUserAPIFailureTyped(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/authen/v1/user_info",
+		Body:   map[string]interface{}{"code": 123456, "msg": "upstream rejected contact request"},
+	})
+
+	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected API error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Code != 123456 {
+		t.Fatalf("code: got %d, want 123456", p.Code)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryAPI)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout should stay empty on API failure, got %q", stdout.String())
+	}
+}
+
+func TestGetUser_UserBasicBatchUsesTypedAPI(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, searchUserDefaultConfig())
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/contact/v3/users/basic_batch?user_id_type=open_id",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"users": []interface{}{
+					map[string]interface{}{"user_id": "ou_a", "name": "Alice"},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, ContactGetUser, []string{"+get-user", "--user-id", "ou_a", "--as", "user", "--format", "json"}, f, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if !bytes.Contains(stub.CapturedBody, []byte(`"ou_a"`)) {
+		t.Fatalf("request body should include user id, got %s", string(stub.CapturedBody))
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"user"`)) {
+		t.Fatalf("stdout should include user object, got %s", stdout.String())
+	}
+}

shortcuts/contact/contact_search_user.go

@@ -15,6 +15,7 @@ import (
 	"strings"
 	"unicode/utf8"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -80,12 +81,6 @@ type searchUserAPIFilter struct {
 	HasEnterpriseEmail  bool     `json:"has_enterprise_email,omitempty"`
 }
 
-type searchUserAPIEnvelope struct {
-	Code int                `json:"code"`
-	Msg  string             `json:"msg"`
-	Data *searchUserAPIData `json:"data"`
-}
-
 type searchUserAPIData struct {
 	Items     []searchUserAPIItem `json:"items"`
 	HasMore   bool                `json:"has_more"`
@@ -216,19 +211,17 @@ func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext
 	if err != nil {
 		return err
 	}
-	if apiResp.StatusCode != http.StatusOK {
-		return output.ErrAPI(apiResp.StatusCode, http.StatusText(apiResp.StatusCode), string(apiResp.RawBody))
+
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return err
+	}
+	respData, err := decodeSearchUserAPIData(data)
+	if err != nil {
+		return err
 	}
 
-	var resp searchUserAPIEnvelope
-	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return output.ErrWithHint(output.ExitInternal, "validation", "unmarshal response failed", err.Error())
-	}
-	if resp.Code != 0 {
-		return output.ErrAPI(resp.Code, resp.Msg, string(apiResp.RawBody))
-	}
-
-	users, hasMore := projectUsers(resp.Data, runtime.Str("lang"), runtime.Config.Brand)
+	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
 	out := searchUserResponse{Users: users, HasMore: hasMore}
 
 	runtime.OutFormat(out, &output.Meta{Count: len(users)}, func(w io.Writer) {
@@ -245,6 +238,20 @@ func executeSearchUserSingle(ctx context.Context, runtime *common.RuntimeContext
 	return nil
 }
 
+func decodeSearchUserAPIData(data map[string]interface{}) (*searchUserAPIData, error) {
+	raw, err := json.Marshal(data)
+	if err != nil {
+		return nil, contactInvalidResponseError("marshal search user response data failed").
+			WithCause(err)
+	}
+	var out searchUserAPIData
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, contactInvalidResponseError("decode search user response data failed").
+			WithCause(err)
+	}
+	return &out, nil
+}
+
 func isHumanReadableFormat(format string) bool {
 	return format == "pretty" || format == "table"
 }
@@ -373,52 +380,74 @@ func rowFromItem(item *searchUserAPIItem, lang string, brand core.LarkBrand) sea
 
 func validateSearchUser(runtime *common.RuntimeContext) error {
 	if !hasAnySearchInput(runtime) {
-		return common.FlagErrorf(
+		return common.ValidationErrorf(
 			"specify at least one of --query, --queries, --user-ids, --has-chatted, --has-enterprise-email, --exclude-external-users, --left-organization",
+		).WithParams(
+			errs.InvalidParam{Name: "--query", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--queries", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--user-ids", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--has-chatted", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--has-enterprise-email", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--exclude-external-users", Reason: "required; specify at least one search input"},
+			errs.InvalidParam{Name: "--left-organization", Reason: "required; specify at least one search input"},
 		)
 	}
 
 	queriesRaw := strings.TrimSpace(runtime.Str("queries"))
 	if queriesRaw != "" {
 		if strings.TrimSpace(runtime.Str("query")) != "" {
-			return common.FlagErrorf("--query and --queries are mutually exclusive")
+			return common.ValidationErrorf("--query and --queries are mutually exclusive").
+				WithParams(
+					errs.InvalidParam{Name: "--query", Reason: "mutually exclusive with --queries"},
+					errs.InvalidParam{Name: "--queries", Reason: "mutually exclusive with --query"},
+				)
 		}
 		if strings.TrimSpace(runtime.Str("user-ids")) != "" {
-			return common.FlagErrorf("--user-ids and --queries are mutually exclusive")
+			return common.ValidationErrorf("--user-ids and --queries are mutually exclusive").
+				WithParams(
+					errs.InvalidParam{Name: "--user-ids", Reason: "mutually exclusive with --queries"},
+					errs.InvalidParam{Name: "--queries", Reason: "mutually exclusive with --user-ids"},
+				)
 		}
 		queries := parseAndDedupQueries(queriesRaw)
 		if len(queries) == 0 {
-			return common.FlagErrorf("--queries: no valid query parsed from %q (separate entries with ',')", queriesRaw)
+			return common.ValidationErrorf("--queries: no valid query parsed from %q (separate entries with ',')", queriesRaw).
+				WithParam("--queries")
 		}
 		if len(queries) > maxFanoutQueries {
-			return common.FlagErrorf("--queries: must be at most %d entries (got %d)", maxFanoutQueries, len(queries))
+			return common.ValidationErrorf("--queries: must be at most %d entries (got %d)", maxFanoutQueries, len(queries)).
+				WithParam("--queries")
 		}
 		for _, q := range queries {
 			if utf8.RuneCountInString(q) > maxSearchUserQueryChars {
-				return common.FlagErrorf("--queries: entry %q exceeds %d characters", q, maxSearchUserQueryChars)
+				return common.ValidationErrorf("--queries: entry %q exceeds %d characters", q, maxSearchUserQueryChars).
+					WithParam("--queries")
 			}
 		}
 	}
 
 	if q := strings.TrimSpace(runtime.Str("query")); q != "" {
 		if utf8.RuneCountInString(q) > maxSearchUserQueryChars {
-			return common.FlagErrorf("--query: length must be between 1 and %d characters", maxSearchUserQueryChars)
+			return common.ValidationErrorf("--query: length must be between 1 and %d characters", maxSearchUserQueryChars).
+				WithParam("--query")
 		}
 	}
 
 	if raw := strings.TrimSpace(runtime.Str("user-ids")); raw != "" {
-		ids, err := common.ResolveOpenIDs("--user-ids", common.SplitCSV(raw), runtime)
+		ids, err := common.ResolveOpenIDsTyped("--user-ids", common.SplitCSV(raw), runtime)
 		if err != nil {
 			return err
 		}
 		if len(ids) == 0 {
-			return common.FlagErrorf("--user-ids: no valid open_id parsed from %q (separate entries with ',')", raw)
+			return common.ValidationErrorf("--user-ids: no valid open_id parsed from %q (separate entries with ',')", raw).
+				WithParam("--user-ids")
 		}
 		if len(ids) > maxSearchUserUserIDs {
-			return common.FlagErrorf("--user-ids: must be at most %d entries", maxSearchUserUserIDs)
+			return common.ValidationErrorf("--user-ids: must be at most %d entries", maxSearchUserUserIDs).
+				WithParam("--user-ids")
 		}
 		for _, id := range ids {
-			if _, err := common.ValidateUserID(id); err != nil {
+			if _, err := common.ValidateUserIDTyped("--user-ids", id); err != nil {
 				return err
 			}
 		}
@@ -429,15 +458,16 @@ func validateSearchUser(runtime *common.RuntimeContext) error {
 	// silent wrong-result bugs.
 	for _, bf := range searchUserBoolFilters {
 		if runtime.Cmd.Flags().Changed(bf.Flag) && !runtime.Bool(bf.Flag) {
-			return common.FlagErrorf(
+			return common.ValidationErrorf(
 				"--%s: pass the flag to enable the filter; omit it to disable filtering (=false is rejected to prevent silent wrong results)",
 				bf.Flag,
-			)
+			).WithParam("--" + bf.Flag)
 		}
 	}
 
 	if n := runtime.Int("page-size"); n < 1 || n > maxSearchUserPageSize {
-		return common.FlagErrorf("--page-size: must be between 1 and %d", maxSearchUserPageSize)
+		return common.ValidationErrorf("--page-size: must be between 1 and %d", maxSearchUserPageSize).
+			WithParam("--page-size")
 	}
 	return nil
 }
@@ -473,7 +503,7 @@ func buildSearchUserBody(runtime *common.RuntimeContext) (*searchUserAPIRequest,
 	hasFilter := false
 
 	if raw := strings.TrimSpace(runtime.Str("user-ids")); raw != "" {
-		ids, err := common.ResolveOpenIDs("--user-ids", common.SplitCSV(raw), runtime)
+		ids, err := common.ResolveOpenIDsTyped("--user-ids", common.SplitCSV(raw), runtime)
 		if err != nil {
 			return nil, err
 		}

shortcuts/contact/contact_search_user_fanout.go

@@ -5,7 +5,6 @@ package contact
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -47,7 +46,7 @@ type fanoutResult struct {
 	Users   []searchUser
 	HasMore bool
 	ErrMsg  string // empty = success
-	ErrCode int    // 0 = success or unknown; otherwise an HTTP status or Lark API code corresponding to the first error
+	Err     error  // original failure, kept for typed all-failed propagation
 }
 
 // isFanoutSummaryFormat gates the per-fanout stderr summary line. Includes csv
@@ -67,7 +66,7 @@ func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int,
 	// Pre-check ctx so queued workers see cancellation before issuing a
 	// request; in-flight workers continue until DoAPI returns.
 	if err := ctx.Err(); err != nil {
-		return fanoutResult{Index: index, Query: query, ErrMsg: err.Error()}
+		return fanoutErrorResult(index, query, err)
 	}
 
 	body := &searchUserAPIRequest{Query: query}
@@ -82,38 +81,29 @@ func runOneQuery(ctx context.Context, runtime *common.RuntimeContext, index int,
 		QueryParams: larkcore.QueryParams{"page_size": []string{strconv.Itoa(runtime.Int("page-size"))}},
 	})
 	if err != nil {
-		return fanoutResult{Index: index, Query: query, ErrMsg: err.Error()}
-	}
-	if apiResp.StatusCode != http.StatusOK {
-		body := strings.TrimSpace(string(apiResp.RawBody))
-		const maxBody = 200
-		if len(body) > maxBody {
-			body = body[:maxBody] + "..."
-		}
-		msg := fmt.Sprintf("HTTP %d %s", apiResp.StatusCode, http.StatusText(apiResp.StatusCode))
-		if body != "" {
-			msg = fmt.Sprintf("%s: %s", msg, body)
-		}
-		return fanoutResult{Index: index, Query: query,
-			ErrMsg:  msg,
-			ErrCode: apiResp.StatusCode}
+		return fanoutErrorResult(index, query, err)
 	}
 
-	var resp searchUserAPIEnvelope
-	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
-		return fanoutResult{Index: index, Query: query,
-			ErrMsg: fmt.Sprintf("parse response failed: %v", err)}
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return fanoutErrorResult(index, query, err)
 	}
-	if resp.Code != 0 {
-		return fanoutResult{Index: index, Query: query,
-			ErrMsg:  fmt.Sprintf("API %d: %s", resp.Code, resp.Msg),
-			ErrCode: resp.Code}
+	respData, err := decodeSearchUserAPIData(data)
+	if err != nil {
+		return fanoutErrorResult(index, query, err)
 	}
 
-	users, hasMore := projectUsers(resp.Data, runtime.Str("lang"), runtime.Config.Brand)
+	users, hasMore := projectUsers(respData, runtime.Str("lang"), runtime.Config.Brand)
 	return fanoutResult{Index: index, Query: query, Users: users, HasMore: hasMore}
 }
 
+func fanoutErrorResult(index int, query string, err error) fanoutResult {
+	if err == nil {
+		return fanoutResult{Index: index, Query: query}
+	}
+	return fanoutResult{Index: index, Query: query, ErrMsg: contactFanoutErrorSummary(err), Err: err}
+}
+
 type fanoutUser struct {
 	searchUser
 	MatchedQuery string `json:"matched_query"`
@@ -146,7 +136,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 	}
 	failed := 0
 	var firstErrMsg, firstErrQuery string
-	var firstErrCode int
+	var firstErr error
 	for i, r := range indexed {
 		out.Queries = append(out.Queries, querySummary{
 			Query:   queries[i],
@@ -158,7 +148,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 			if firstErrMsg == "" {
 				firstErrMsg = r.ErrMsg
 				firstErrQuery = queries[i]
-				firstErrCode = r.ErrCode
+				firstErr = r.Err
 			}
 			continue
 		}
@@ -169,18 +159,7 @@ func buildFanoutResponse(queries []string, results []fanoutResult) (*fanoutRespo
 	if failed == len(queries) && len(queries) > 0 {
 		msg := fmt.Sprintf("all %d queries failed; first: %s (query=%q)",
 			len(queries), firstErrMsg, firstErrQuery)
-		// Only the HTTP-status / Lark-API-code branches in runOneQuery populate
-		// ErrCode; transport, parse, panic, and ctx-canceled stay at 0. Code 0
-		// means success in the Lark protocol, so don't pretend it's an API error
-		// when we have nothing structured to report.
-		if firstErrCode != 0 {
-			return nil, output.ErrAPI(firstErrCode, msg, "")
-		}
-		// No structured API code — the failure was transport, parse, panic, or
-		// cancellation. Suggest the actionable next step rather than shipping
-		// an empty hint that would leave the calling agent with nothing to do.
-		return nil, output.ErrWithHint(output.ExitInternal, "fanout", msg,
-			"retry the command; if it persists, narrow --queries to a single term to isolate the failing input")
+		return nil, contactFanoutAllFailedError(firstErr, msg)
 	}
 	return out, nil
 }

shortcuts/contact/contact_search_user_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -16,10 +15,10 @@ import (
 	"time"
 	"unicode/utf8"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	"github.com/spf13/cobra"
 )
@@ -254,6 +253,16 @@ func TestRowFromItem_CrossTenantEmptyEmailNoPanic(t *testing.T) {
 	}
 }
 
+func TestProjectUsers_NilData(t *testing.T) {
+	users, hasMore := projectUsers(nil, "", core.BrandFeishu)
+	if users == nil {
+		t.Fatalf("users should be an empty slice, not nil")
+	}
+	if len(users) != 0 || hasMore {
+		t.Fatalf("projectUsers(nil): got users=%v hasMore=%v", users, hasMore)
+	}
+}
+
 func TestValidateSearchUser_AllEmpty_Errors(t *testing.T) {
 	cmd := newSearchUserTestCommand()
 	rt := common.TestNewRuntimeContext(cmd, searchUserDefaultConfig())
@@ -479,6 +488,26 @@ func TestBuildBody_UserIDsResolveAndDedup(t *testing.T) {
 	}
 }
 
+func TestBuildBody_UserIDsMeWithoutLoginReturnsTypedError(t *testing.T) {
+	cmd := newSearchUserTestCommand()
+	_ = cmd.Flags().Set("user-ids", "me")
+	cfg := searchUserDefaultConfig()
+	cfg.UserOpenId = ""
+	rt := common.TestNewRuntimeContext(cmd, cfg)
+
+	body, err := buildSearchUserBody(rt)
+	if err == nil {
+		t.Fatalf("expected error, got body %+v", body)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryValidation)
+	}
+}
+
 func TestValidateSearchUser_PageSizeOutOfRange_Errors(t *testing.T) {
 	for _, n := range []int{0, 31} {
 		cmd := newSearchUserTestCommand()
@@ -504,6 +533,20 @@ func TestValidateSearchUser_PageSizeBoundaries_OK(t *testing.T) {
 	}
 }
 
+func TestDecodeSearchUserAPIData_MarshalFailureTyped(t *testing.T) {
+	_, err := decodeSearchUserAPIData(map[string]interface{}{"bad": func() {}})
+	if err == nil {
+		t.Fatalf("expected marshal failure")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("problem type: got %s/%s", p.Category, p.Subtype)
+	}
+}
+
 // mountAndRun mounts the shortcut under a parent cobra command and runs it
 // with the given args. Mirrors the pattern used in other shortcut packages.
 func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
@@ -1011,6 +1054,13 @@ func TestRunOneQuery_APINonZeroCode(t *testing.T) {
 	if got.ErrMsg != "API 99991663: rate limited" {
 		t.Errorf("ErrMsg = %q, want 'API 99991663: rate limited'", got.ErrMsg)
 	}
+	p, ok := errs.ProblemOf(got.Err)
+	if !ok {
+		t.Fatalf("expected typed problem on fanout result, got %T", got.Err)
+	}
+	if p.Code != 99991663 {
+		t.Errorf("problem code: got %d, want 99991663", p.Code)
+	}
 	if got.Users != nil || got.HasMore {
 		t.Errorf("on error, Users/HasMore must be zero values; got %+v", got)
 	}
@@ -1032,8 +1082,15 @@ func TestRunOneQuery_HTTPNon200(t *testing.T) {
 	if !strings.Contains(got.ErrMsg, "upstream_unavailable") {
 		t.Errorf("ErrMsg should include response body for diagnosis; got %q", got.ErrMsg)
 	}
-	if got.ErrCode != 503 {
-		t.Errorf("ErrCode = %d, want 503", got.ErrCode)
+	p, ok := errs.ProblemOf(got.Err)
+	if !ok {
+		t.Fatalf("expected typed problem on fanout result, got %T", got.Err)
+	}
+	if p.Code != 503 {
+		t.Errorf("problem code: got %d, want 503", p.Code)
+	}
+	if p.Category != errs.CategoryNetwork {
+		t.Errorf("problem category: got %q, want %q", p.Category, errs.CategoryNetwork)
 	}
 }
 
@@ -1080,6 +1137,16 @@ func TestRunOneQuery_TransportError(t *testing.T) {
 	}
 }
 
+func TestFanoutErrorResult_NilErrorIsSuccess(t *testing.T) {
+	got := fanoutErrorResult(4, "alice", nil)
+	if got.Index != 4 || got.Query != "alice" {
+		t.Fatalf("Index/Query mismatch: %+v", got)
+	}
+	if got.ErrMsg != "" || got.Err != nil {
+		t.Fatalf("nil error should produce a success result, got %+v", got)
+	}
+}
+
 func TestFanoutAssemble_OrderAndShape(t *testing.T) {
 	results := []fanoutResult{
 		{Index: 1, Query: "bob", Users: []searchUser{{OpenID: "ou_b"}}, HasMore: true},
@@ -1136,7 +1203,7 @@ func TestFanoutAssemble_AllFailed_ReturnsError(t *testing.T) {
 }
 
 // When all queries fail with no structured Lark API code (transport, parse,
-// panic, ctx-canceled), the returned ExitError must carry an actionable
+// panic, ctx-canceled), the returned typed error must carry an actionable
 // hint so the calling agent has a next step to try instead of giving up.
 func TestFanoutAssemble_AllFailed_NoCode_HasActionableHint(t *testing.T) {
 	results := []fanoutResult{
@@ -1147,28 +1214,38 @@ func TestFanoutAssemble_AllFailed_NoCode_HasActionableHint(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected error when all queries failed")
 	}
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T", err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
 	}
-	if exitErr.Detail == nil {
-		t.Fatalf("expected Detail, got nil")
+	if p.Category != errs.CategoryInternal {
+		t.Fatalf("category: got %q, want %q", p.Category, errs.CategoryInternal)
 	}
-	if exitErr.Detail.Hint == "" {
+	if p.Hint == "" {
 		t.Errorf("expected non-empty Hint so agents have a next step; got empty")
 	}
-	if !strings.Contains(exitErr.Detail.Hint, "retry") {
-		t.Errorf("hint should suggest retry as the first action; got %q", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "retry") {
+		t.Errorf("hint should suggest retry as the first action; got %q", p.Hint)
 	}
 }
 
-// Codes from the first failure must propagate through output.ErrAPI so the
-// CLI's exit-code classifier sees the real signal (e.g., 99991663 rate limit)
+// Codes from the first failure must propagate through typed problem fields so
+// the CLI's exit-code classifier sees the real signal (e.g., 99991663 rate limit)
 // instead of 0, which would mean "success" in the Lark protocol.
 func TestFanoutAssemble_AllFailed_PropagatesFirstCode(t *testing.T) {
 	results := []fanoutResult{
-		{Index: 0, Query: "alice", ErrMsg: "API 99991663: rate limit", ErrCode: 99991663},
-		{Index: 1, Query: "bob", ErrMsg: "HTTP 500", ErrCode: 500},
+		{
+			Index:  0,
+			Query:  "alice",
+			ErrMsg: "API 99991663: rate limit",
+			Err:    errs.NewAPIError(errs.SubtypeRateLimit, "rate limit").WithCode(99991663),
+		},
+		{
+			Index:  1,
+			Query:  "bob",
+			ErrMsg: "HTTP 500",
+			Err:    errs.NewNetworkError(errs.SubtypeNetworkServer, "HTTP 500").WithCode(500),
+		},
 	}
 	_, err := buildFanoutResponse([]string{"alice", "bob"}, results)
 	if err == nil {
@@ -1177,6 +1254,16 @@ func TestFanoutAssemble_AllFailed_PropagatesFirstCode(t *testing.T) {
 	if !strings.Contains(err.Error(), "rate limit") {
 		t.Errorf("error should contain first ErrMsg; got %v", err)
 	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T", err)
+	}
+	if p.Code != 99991663 {
+		t.Errorf("problem code: got %d, want 99991663", p.Code)
+	}
+	if p.Subtype != errs.SubtypeRateLimit {
+		t.Errorf("problem subtype: got %q, want %q", p.Subtype, errs.SubtypeRateLimit)
+	}
 }
 
 func TestFanoutAssemble_PartialFailureOK(t *testing.T) {
@@ -1220,6 +1307,37 @@ func TestFanoutAssemble_NoTopLevelHasMore(t *testing.T) {
 	}
 }
 
+func TestPrettyFanoutUserRows(t *testing.T) {
+	rows := prettyFanoutUserRows([]fanoutUser{
+		{
+			searchUser: searchUser{
+				OpenID:          "ou_a",
+				LocalizedName:   "Alice",
+				Department:      strings.Repeat("d", 80),
+				EnterpriseEmail: "alice@example.com",
+				HasChatted:      true,
+				ChatRecencyHint: "Contacted yesterday",
+			},
+			MatchedQuery: "alice",
+		},
+	})
+	if len(rows) != 1 {
+		t.Fatalf("rows: got %d, want 1", len(rows))
+	}
+	row := rows[0]
+	for _, key := range []string{"matched_query", "localized_name", "department", "enterprise_email", "has_chatted", "chat_recency_hint", "open_id"} {
+		if _, ok := row[key]; !ok {
+			t.Fatalf("row missing key %q: %+v", key, row)
+		}
+	}
+	if row["matched_query"] != "alice" || row["open_id"] != "ou_a" {
+		t.Fatalf("row identity fields: %+v", row)
+	}
+	if len(row["department"].(string)) >= 80 {
+		t.Fatalf("department should be truncated for table display, got %q", row["department"])
+	}
+}
+
 // Verifies that with the auto-pagination flags removed, --page-all / --page-limit
 // are no longer accepted. cobra must reject the unknown flag at parse time —
 // no stub is registered because the command should never reach the API.

shortcuts/doc/clipboard.go

@@ -11,6 +11,8 @@ import (
 	"regexp"
 	"runtime"
 	"strings"
+
+	"github.com/larksuite/cli/errs"
 )
 
 // readClipboardImageBytes reads the current clipboard image and returns the
@@ -35,13 +37,13 @@ func readClipboardImageBytes() ([]byte, error) {
 	case "linux":
 		data, err = readClipboardLinux()
 	default:
-		return nil, fmt.Errorf("clipboard image upload is not supported on %s", runtime.GOOS)
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image upload is not supported on %s", runtime.GOOS)
 	}
 	if err != nil {
 		return nil, err
 	}
 	if len(data) == 0 {
-		return nil, fmt.Errorf("clipboard contains no image data")
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data")
 	}
 	return data, nil
 }
@@ -91,9 +93,9 @@ func readClipboardDarwin() ([]byte, error) {
 	}
 
 	if stderrText != "" {
-		return nil, fmt.Errorf("clipboard contains no image data (osascript: %s)", stderrText)
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data (osascript: %s)", stderrText)
 	}
-	return nil, fmt.Errorf("clipboard contains no image data")
+	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data")
 }
 
 // runOsascript invokes osascript with a single AppleScript expression and
@@ -188,14 +190,14 @@ func decodeOsascriptData(s string) ([]byte, error) {
 // decodeHex decodes an uppercase hex string (as produced by osascript) to bytes.
 func decodeHex(h string) ([]byte, error) {
 	if len(h)%2 != 0 {
-		return nil, fmt.Errorf("odd hex length")
+		return nil, fmt.Errorf("odd hex length") //nolint:forbidigo // intermediate decode helper; result discarded by caller on error
 	}
 	b := make([]byte, len(h)/2)
 	for i := 0; i < len(h); i += 2 {
 		hi := hexVal(h[i])
 		lo := hexVal(h[i+1])
 		if hi < 0 || lo < 0 {
-			return nil, fmt.Errorf("invalid hex char at %d", i)
+			return nil, fmt.Errorf("invalid hex char at %d", i) //nolint:forbidigo // intermediate decode helper; result discarded by caller on error
 		}
 		b[i/2] = byte(hi<<4 | lo)
 	}
@@ -237,12 +239,12 @@ $img.Save($ms, [System.Drawing.Imaging.ImageFormat]::Png)
 		if msg == "" {
 			msg = err.Error()
 		}
-		return nil, fmt.Errorf("clipboard read failed (%s)", msg)
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard read failed (%s)", msg)
 	}
 	b64 := strings.TrimSpace(string(out))
 	data, decErr := base64.StdEncoding.DecodeString(b64)
 	if decErr != nil {
-		return nil, fmt.Errorf("clipboard image decode failed: %w", decErr)
+		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image decode failed: %s", decErr).WithCause(decErr)
 	}
 	return data, nil
 }
@@ -325,15 +327,15 @@ func readClipboardLinux() ([]byte, error) {
 		foundTool = true
 		out, err := exec.Command(t.name, t.args...).Output()
 		if err != nil {
-			lastErr = fmt.Errorf("clipboard image read failed via %s: %w", t.name, err)
+			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard image read failed via %s: %s", t.name, err).WithCause(err)
 			continue
 		}
 		if len(out) == 0 {
-			lastErr = fmt.Errorf("clipboard contains no image data (%s returned empty output)", t.name)
+			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no image data (%s returned empty output)", t.name)
 			continue
 		}
 		if t.validatePNG && !hasPNGMagic(out) {
-			lastErr = fmt.Errorf("clipboard contains no PNG image data (%s output is not a PNG)", t.name)
+			lastErr = errs.NewValidationError(errs.SubtypeFailedPrecondition, "clipboard contains no PNG image data (%s output is not a PNG)", t.name)
 			continue
 		}
 		return out, nil
@@ -342,8 +344,8 @@ func readClipboardLinux() ([]byte, error) {
 	if foundTool && lastErr != nil {
 		return nil, lastErr
 	}
-	return nil, fmt.Errorf(
-		"clipboard image read failed: no supported tool found. " +
-			"Install one of xclip, wl-clipboard, or xsel via your distro's package manager " +
+	return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
+		"clipboard image read failed: no supported tool found. "+
+			"Install one of xclip, wl-clipboard, or xsel via your distro's package manager "+
 			"(apt, dnf, pacman, apk, brew, etc.).")
 }

shortcuts/doc/doc_errors.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import "github.com/larksuite/cli/errs"
+
+// wrapDocNetworkErr returns err unchanged when it is already a typed errs.*
+// error (preserving its subtype / code / log_id from the runtime boundary),
+// and only wraps a raw, unclassified error as a transport-level network error.
+func wrapDocNetworkErr(err error, format string, args ...any) error {
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
+	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
+}

shortcuts/doc/doc_media_download.go

@@ -10,8 +10,8 @@ import (
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -51,10 +51,10 @@ var DocMediaDownload = common.Shortcut{
 		overwrite := runtime.Bool("overwrite")
 
 		if err := validate.ResourceName(token, "--token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
 		}
 		if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-			return output.ErrValidation("unsafe output path: %s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Downloading: %s %s\n", mediaType, common.MaskToken(token))
@@ -73,7 +73,7 @@ var DocMediaDownload = common.Shortcut{
 			ApiPath:    apiPath,
 		})
 		if err != nil {
-			return output.ErrNetwork("download failed: %v", err)
+			return wrapDocNetworkErr(err, "download failed: %v", err)
 		}
 		defer resp.Body.Close()
 
@@ -86,14 +86,14 @@ var DocMediaDownload = common.Shortcut{
 		// Validate final path after extension append
 		if finalPath != outputPath {
 			if _, err := runtime.ResolveSavePath(finalPath); err != nil {
-				return output.ErrValidation("unsafe output path: %s", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
 			}
 		}
 
 		// Overwrite check on final path (after extension detection)
 		if !overwrite {
 			if _, statErr := runtime.FileIO().Stat(finalPath); statErr == nil {
-				return output.ErrValidation("output file already exists: %s (use --overwrite to replace)", finalPath)
+				return errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", finalPath).WithParam("--output")
 			}
 		}
 
@@ -102,7 +102,7 @@ var DocMediaDownload = common.Shortcut{
 			ContentLength: resp.ContentLength,
 		}, resp.Body)
 		if err != nil {
-			return common.WrapSaveErrorByCategory(err, "io")
+			return common.WrapSaveErrorTyped(err)
 		}
 
 		savedPath, _ := runtime.ResolveSavePath(finalPath)

shortcuts/doc/doc_media_insert.go

@@ -15,8 +15,8 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -67,10 +67,10 @@ var DocMediaInsert = common.Shortcut{
 		filePath := runtime.Str("file")
 		fromClipboard := runtime.Bool("from-clipboard")
 		if filePath == "" && !fromClipboard {
-			return common.FlagErrorf("one of --file or --from-clipboard is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "one of --file or --from-clipboard is required")
 		}
 		if filePath != "" && fromClipboard {
-			return common.FlagErrorf("--file and --from-clipboard are mutually exclusive")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file and --from-clipboard are mutually exclusive")
 		}
 
 		docRef, err := parseDocumentRef(runtime.Str("doc"))
@@ -78,7 +78,7 @@ var DocMediaInsert = common.Shortcut{
 			return err
 		}
 		if docRef.Kind == "doc" {
-			return output.ErrValidation("docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
 		}
 		rawSelection := runtime.Str("selection-with-ellipsis")
 		trimmedSelection := strings.TrimSpace(rawSelection)
@@ -87,36 +87,36 @@ var DocMediaInsert = common.Shortcut{
 		// trim-to-empty would make +media-insert fall back to append-mode and
 		// write at the wrong location.
 		if rawSelection != "" && trimmedSelection == "" {
-			return output.ErrValidation("--selection-with-ellipsis must not be blank or whitespace-only")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--selection-with-ellipsis must not be blank or whitespace-only").WithParam("--selection-with-ellipsis")
 		}
 		if runtime.Bool("before") && trimmedSelection == "" {
-			return output.ErrValidation("--before requires --selection-with-ellipsis")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--before requires --selection-with-ellipsis").WithParam("--before")
 		}
 		if view := runtime.Str("file-view"); view != "" {
 			if _, ok := fileViewMap[view]; !ok {
-				return output.ErrValidation("invalid --file-view value %q, expected one of: card | preview | inline", view)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --file-view value %q, expected one of: card | preview | inline", view).WithParam("--file-view")
 			}
 			if runtime.Str("type") != "file" {
-				return output.ErrValidation("--file-view only applies when --type=file")
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-view only applies when --type=file").WithParam("--file-view")
 			}
 		}
 		widthChanged := runtime.Changed("width")
 		heightChanged := runtime.Changed("height")
 		if (widthChanged || heightChanged) && runtime.Str("type") != "image" {
-			return output.ErrValidation("--width/--height only apply when --type=image")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width/--height only apply when --type=image")
 		}
 		if widthChanged && runtime.Int("width") <= 0 {
-			return output.ErrValidation("--width must be a positive integer")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width must be a positive integer").WithParam("--width")
 		}
 		if heightChanged && runtime.Int("height") <= 0 {
-			return output.ErrValidation("--height must be a positive integer")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--height must be a positive integer").WithParam("--height")
 		}
 		const maxDimension = 10000
 		if widthChanged && runtime.Int("width") > maxDimension {
-			return output.ErrValidation("--width must not exceed %d pixels", maxDimension)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width must not exceed %d pixels", maxDimension).WithParam("--width")
 		}
 		if heightChanged && runtime.Int("height") > maxDimension {
-			return output.ErrValidation("--height must not exceed %d pixels", maxDimension)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--height must not exceed %d pixels", maxDimension).WithParam("--height")
 		}
 		return nil
 	},
@@ -269,10 +269,10 @@ var DocMediaInsert = common.Shortcut{
 		} else {
 			stat, err := runtime.FileIO().Stat(filePath)
 			if err != nil {
-				return common.WrapInputStatError(err, "file not found")
+				return common.WrapInputStatErrorTyped(err, "file not found")
 			}
 			if !stat.Mode().IsRegular() {
-				return output.ErrValidation("file must be a regular file: %s", filePath)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must be a regular file: %s", filePath).WithParam("--file")
 			}
 			fileSize = stat.Size()
 			fileName = filepath.Base(filePath)
@@ -284,7 +284,7 @@ var DocMediaInsert = common.Shortcut{
 		}
 
 		// Step 1: Get document root block to find where to insert
-		rootData, err := runtime.CallAPI("GET",
+		rootData, err := runtime.CallAPITyped("GET",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s", validate.EncodePathSegment(documentID), validate.EncodePathSegment(documentID)),
 			nil, nil)
 		if err != nil {
@@ -318,7 +318,7 @@ var DocMediaInsert = common.Shortcut{
 		// Step 2: Create an empty block at the target position
 		fmt.Fprintf(runtime.IO().ErrOut, "Creating block at index %d\n", insertIndex)
 
-		createData, err := runtime.CallAPI("POST",
+		createData, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s/children", validate.EncodePathSegment(documentID), validate.EncodePathSegment(parentBlockID)),
 			nil, buildCreateBlockData(mediaType, insertIndex, fileViewType))
 		if err != nil {
@@ -328,7 +328,7 @@ var DocMediaInsert = common.Shortcut{
 		blockId, uploadParentNode, replaceBlockID := extractCreatedBlockTargets(createData, mediaType)
 
 		if blockId == "" {
-			return output.Errorf(output.ExitAPI, "api_error", "failed to create block: no block_id returned")
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "failed to create block: no block_id returned")
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Block created: %s\n", blockId)
@@ -340,7 +340,7 @@ var DocMediaInsert = common.Shortcut{
 		// later steps should try to remove it instead of leaving an empty artifact.
 		rollback := func() error {
 			fmt.Fprintf(runtime.IO().ErrOut, "Rolling back: deleting block %s\n", blockId)
-			_, err := runtime.CallAPI("DELETE",
+			_, err := runtime.CallAPITyped("DELETE",
 				fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s/children/batch_delete", validate.EncodePathSegment(documentID), validate.EncodePathSegment(parentBlockID)),
 				nil, buildDeleteBlockData(insertIndex))
 			return err
@@ -379,14 +379,14 @@ var DocMediaInsert = common.Shortcut{
 				} else {
 					f, openErr := runtime.FileIO().Open(filePath)
 					if openErr != nil {
-						return withRollbackWarning(output.ErrValidation(
+						return withRollbackWarning(errs.NewValidationError(errs.SubtypeInvalidArgument,
 							"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
 					}
 					nativeW, nativeH, dimErr = detectImageDimensions(f)
 					f.Close()
 				}
 				if dimErr != nil {
-					return withRollbackWarning(output.ErrValidation(
+					return withRollbackWarning(errs.NewValidationError(errs.SubtypeInvalidArgument,
 						"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
 				}
 				dims := computeMissingDimension(userWidth, userHeight, nativeW, nativeH)
@@ -417,7 +417,7 @@ var DocMediaInsert = common.Shortcut{
 		// Step 4: Bind file token to block via batch_update
 		fmt.Fprintf(runtime.IO().ErrOut, "Binding uploaded media to block %s\n", replaceBlockID)
 
-		if _, err := runtime.CallAPI("PATCH",
+		if _, err := runtime.CallAPITyped("PATCH",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/batch_update", validate.EncodePathSegment(documentID)),
 			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption, finalWidth, finalHeight)); err != nil {
 			return withRollbackWarning(err)
@@ -512,10 +512,10 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 	case "docx":
 		return docRef.Token, nil
 	case "doc":
-		return "", output.ErrValidation("docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
 	case "wiki":
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node: %s\n", common.MaskToken(docRef.Token))
-		data, err := runtime.CallAPI(
+		data, err := runtime.CallAPITyped(
 			"GET",
 			"/open-apis/wiki/v2/spaces/get_node",
 			map[string]interface{}{"token": docRef.Token},
@@ -529,16 +529,16 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 		objType := common.GetString(node, "obj_type")
 		objToken := common.GetString(node, "obj_token")
 		if objType == "" || objToken == "" {
-			return "", output.Errorf(output.ExitAPI, "api_error", "wiki get_node returned incomplete node data")
+			return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki get_node returned incomplete node data")
 		}
 		if objType != "docx" {
-			return "", output.ErrValidation("wiki resolved to %q, but docs +media-insert only supports docx documents", objType)
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "wiki resolved to %q, but docs +media-insert only supports docx documents", objType).WithParam("--doc")
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolved wiki to docx: %s\n", common.MaskToken(objToken))
 		return objToken, nil
 	default:
-		return "", output.ErrValidation("docs +media-insert only supports docx documents")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents").WithParam("--doc")
 	}
 }
 
@@ -622,7 +622,7 @@ func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption strin
 func extractAppendTarget(rootData map[string]interface{}, fallbackBlockID string) (parentBlockID string, insertIndex int, children []interface{}, err error) {
 	block, _ := rootData["block"].(map[string]interface{})
 	if len(block) == 0 {
-		return "", 0, nil, output.Errorf(output.ExitAPI, "api_error", "failed to query document root block")
+		return "", 0, nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "failed to query document root block")
 	}
 
 	parentBlockID = fallbackBlockID
@@ -653,12 +653,10 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 
 	matches := common.GetSlice(result, "matches")
 	if len(matches) == 0 {
-		return 0, output.ErrWithHint(
-			output.ExitValidation,
-			"no_match",
-			fmt.Sprintf("locate-doc did not find any block matching selection (%s)", redactSelection(selection)),
-			"check spelling or use 'start...end' syntax to narrow the selection",
-		)
+		return 0, errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"locate-doc did not find any block matching selection (%s)", redactSelection(selection)).
+			WithParam("--selection-with-ellipsis").
+			WithHint("check spelling or use 'start...end' syntax to narrow the selection")
 	}
 	if len(matches) > 1 {
 		// Silently picking the first match surprises users whose selection appears
@@ -682,7 +680,7 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		}
 	}
 	if anchorBlockID == "" {
-		return 0, output.Errorf(output.ExitAPI, "api_error", "locate-doc response missing anchor_block_id")
+		return 0, errs.NewInternalError(errs.SubtypeInvalidResponse, "locate-doc response missing anchor_block_id")
 	}
 	parentBlockID := common.GetString(matchMap, "parent_block_id")
 
@@ -740,7 +738,7 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		nextParent = "" // clear hint after first use
 		if parent == "" || parent == cur {
 			// Need to fetch this block to find its parent.
-			data, err := runtime.CallAPI("GET",
+			data, err := runtime.CallAPITyped("GET",
 				fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/%s",
 					validate.EncodePathSegment(documentID), validate.EncodePathSegment(cur)),
 				nil, nil)
@@ -757,12 +755,10 @@ func locateInsertIndex(runtime *common.RuntimeContext, documentID string, select
 		walkDepth++
 	}
 
-	return 0, output.ErrWithHint(
-		output.ExitValidation,
-		"block_not_reachable",
-		fmt.Sprintf("block matching selection (%s) is not reachable from document root", redactSelection(selection)),
-		"try a top-level heading or paragraph as the selection",
-	)
+	return 0, errs.NewValidationError(errs.SubtypeInvalidArgument,
+		"block matching selection (%s) is not reachable from document root", redactSelection(selection)).
+		WithParam("--selection-with-ellipsis").
+		WithHint("try a top-level heading or paragraph as the selection")
 }
 
 func extractCreatedBlockTargets(createData map[string]interface{}, mediaType string) (blockID, uploadParentNode, replaceBlockID string) {

shortcuts/doc/doc_media_preview.go

@@ -10,8 +10,8 @@ import (
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -45,11 +45,11 @@ var DocMediaPreview = common.Shortcut{
 		overwrite := runtime.Bool("overwrite")
 
 		if err := validate.ResourceName(token, "--token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
 		}
 		// Early path validation before API call (final validation after auto-extension below)
 		if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-			return output.ErrValidation("unsafe output path: %s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Previewing: media %s\n", common.MaskToken(token))
@@ -65,7 +65,7 @@ var DocMediaPreview = common.Shortcut{
 			},
 		})
 		if err != nil {
-			return output.ErrNetwork("preview failed: %v", err)
+			return wrapDocNetworkErr(err, "preview failed: %v", err)
 		}
 		defer resp.Body.Close()
 
@@ -74,14 +74,14 @@ var DocMediaPreview = common.Shortcut{
 		// Validate final path after extension append
 		if finalPath != outputPath {
 			if _, err := runtime.ResolveSavePath(finalPath); err != nil {
-				return output.ErrValidation("unsafe output path: %s", err)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).WithParam("--output").WithCause(err)
 			}
 		}
 
 		// Overwrite check on final path (after extension detection)
 		if !overwrite {
 			if _, statErr := runtime.FileIO().Stat(finalPath); statErr == nil {
-				return output.ErrValidation("output file already exists: %s (use --overwrite to replace)", finalPath)
+				return errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", finalPath).WithParam("--output")
 			}
 		}
 
@@ -90,7 +90,7 @@ var DocMediaPreview = common.Shortcut{
 			ContentLength: resp.ContentLength,
 		}, resp.Body)
 		if err != nil {
-			return common.WrapSaveErrorByCategory(err, "io")
+			return common.WrapSaveErrorTyped(err)
 		}
 
 		savedPath, _ := runtime.ResolveSavePath(finalPath)

shortcuts/doc/doc_media_upload.go

@@ -9,8 +9,8 @@ import (
 	"io"
 	"path/filepath"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -84,10 +84,10 @@ var DocMediaUpload = common.Shortcut{
 		// Validate file
 		stat, err := runtime.FileIO().Stat(filePath)
 		if err != nil {
-			return common.WrapInputStatError(err, "file not found")
+			return common.WrapInputStatErrorTyped(err, "file not found")
 		}
 		if !stat.Mode().IsRegular() {
-			return output.ErrValidation("file must be a regular file: %s", filePath)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "file must be a regular file: %s", filePath).WithParam("--file")
 		}
 
 		fileName := filepath.Base(filePath)

shortcuts/doc/docs_create.go

@@ -5,35 +5,13 @@ package doc
 
 import (
 	"context"
-	"strings"
-
-	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// v1CreateFlags returns the flag definitions for the v1 (MCP) create path.
+// v1CreateFlags returns hidden parse-only compatibility flags for old v1 commands.
 func v1CreateFlags() []common.Flag {
-	return []common.Flag{
-		{Name: "title", Desc: "document title", Hidden: true},
-		{Name: "markdown", Desc: "Markdown content (Lark-flavored)", Hidden: true, Input: []string{common.File, common.Stdin}},
-		{Name: "folder-token", Desc: "parent folder token", Hidden: true},
-		{Name: "wiki-node", Desc: "wiki node token", Hidden: true},
-		{Name: "wiki-space", Desc: "wiki space ID (use my_library for personal library)", Hidden: true},
-	}
-}
-
-var docsCreateFlagVersions = buildFlagVersionMap(v1CreateFlags(), v2CreateFlags())
-
-// useV2Create returns true when the v2 (OpenAPI) create path should be used.
-// Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags.
-func useV2Create(runtime *common.RuntimeContext) bool {
-	if runtime.Str("api-version") == "v2" {
-		return true
-	}
-	return runtime.Str("content") != "" ||
-		runtime.Str("parent-token") != "" ||
-		runtime.Str("parent-position") != ""
+	return docsLegacyFlagDefinitions(docsCreateLegacyFlags())
 }
 
 var DocsCreate = common.Shortcut{
@@ -43,213 +21,25 @@ var DocsCreate = common.Shortcut{
 	Risk:        "write",
 	AuthTypes:   []string{"user", "bot"},
 	Scopes:      []string{"docx:document:create"},
-	Tips:        docsVersionSelectionTips,
+	PostMount:   installDocsShortcutHelp("+create"),
 	Flags: concatFlags(
 		[]common.Flag{
-			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
+			docsAPIVersionCompatFlag(),
 		},
-		v1CreateFlags(),
 		v2CreateFlags(),
+		v1CreateFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Create(runtime) {
-			return validateCreateV2(ctx, runtime)
-		}
-		return validateCreateV1(ctx, runtime)
+		return validateCreateV2(ctx, runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		if useV2Create(runtime) {
-			return dryRunCreateV2(ctx, runtime)
-		}
-		return dryRunCreateV1(ctx, runtime)
+		return dryRunCreateV2(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Create(runtime) {
-			return executeCreateV2(ctx, runtime)
-		}
-		return executeCreateV1(ctx, runtime)
-	},
-	PostMount: func(cmd *cobra.Command) {
-		installVersionedHelp(cmd, "v1", docsCreateFlagVersions)
+		return executeCreateV2(ctx, runtime)
 	},
 }
 
-// ── V1 (MCP) implementation ──
-
-func validateCreateV1(_ context.Context, runtime *common.RuntimeContext) error {
-	if runtime.Str("markdown") == "" {
-		return common.FlagErrorf("--markdown is required")
-	}
-	count := 0
-	if runtime.Str("folder-token") != "" {
-		count++
-	}
-	if runtime.Str("wiki-node") != "" {
-		count++
-	}
-	if runtime.Str("wiki-space") != "" {
-		count++
-	}
-	if count > 1 {
-		return common.FlagErrorf("--folder-token, --wiki-node, and --wiki-space are mutually exclusive")
-	}
-	return nil
-}
-
-func dryRunCreateV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	args := buildCreateArgsV1(runtime)
-	d := common.NewDryRunAPI().
-		POST(common.MCPEndpoint(runtime.Config.Brand)).
-		Desc("MCP tool: create-doc").
-		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "create-doc", "arguments": args}}).
-		Set("mcp_tool", "create-doc").Set("args", args)
-	if runtime.IsBot() {
-		d.Desc("After create-doc succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new document.")
-	}
-	return d
-}
-
-func executeCreateV1(_ context.Context, runtime *common.RuntimeContext) error {
-	warnDeprecatedV1(runtime, "+create")
-	// Surface callout type= hint so users know to switch to background-color/
-	// border-color when they want a colored callout. Non-blocking, advisory.
-	if md := runtime.Str("markdown"); md != "" {
-		WarnCalloutType(md, runtime.IO().ErrOut)
-	}
-	args := buildCreateArgsV1(runtime)
-	result, err := common.CallMCPTool(runtime, "create-doc", args)
-	if err != nil {
-		return err
-	}
-	augmentCreateResultV1(runtime, result)
-	normalizeWhiteboardResult(result, runtime.Str("markdown"))
-	runtime.Out(result, nil)
-	return nil
-}
-
-func buildCreateArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
-	md := runtime.Str("markdown")
-	args := map[string]interface{}{
-		"markdown": md,
-	}
-	if v := runtime.Str("title"); v != "" {
-		args["title"] = v
-	}
-	if v := runtime.Str("folder-token"); v != "" {
-		args["folder_token"] = v
-	}
-	if v := runtime.Str("wiki-node"); v != "" {
-		args["wiki_node"] = v
-	}
-	if v := runtime.Str("wiki-space"); v != "" {
-		args["wiki_space"] = v
-	}
-	return args
-}
-
-type docsPermissionTarget struct {
-	Token string
-	Type  string
-}
-
-func augmentCreateResultV1(runtime *common.RuntimeContext, result map[string]interface{}) {
-	target := selectPermissionTarget(result)
-	if grant := common.AutoGrantCurrentUserDrivePermission(runtime, target.Token, target.Type); grant != nil {
-		result["permission_grant"] = grant
-	}
-	fallbackDocURLV1(runtime, result)
-}
-
-// fallbackDocURLV1 fills result.doc_url with a brand-standard URL when the MCP
-// response did not include one but did include a doc_id. This protects against
-// degraded MCP responses (multi-content, non-JSON text) where ExtractMCPResult
-// drops structured fields.
-func fallbackDocURLV1(runtime *common.RuntimeContext, result map[string]interface{}) {
-	if strings.TrimSpace(common.GetString(result, "doc_url")) != "" {
-		return
-	}
-	docID := strings.TrimSpace(common.GetString(result, "doc_id"))
-	if docID == "" {
-		return
-	}
-	if u := common.BuildResourceURL(runtime.Config.Brand, "docx", docID); u != "" {
-		result["doc_url"] = u
-	}
-}
-
-func selectPermissionTarget(result map[string]interface{}) docsPermissionTarget {
-	if ref, ok := parsePermissionTargetFromURL(common.GetString(result, "doc_url")); ok {
-		return ref
-	}
-	docID := strings.TrimSpace(common.GetString(result, "doc_id"))
-	if docID != "" {
-		return docsPermissionTarget{Token: docID, Type: "docx"}
-	}
-	return docsPermissionTarget{}
-}
-
-func parsePermissionTargetFromURL(docURL string) (docsPermissionTarget, bool) {
-	if strings.TrimSpace(docURL) == "" {
-		return docsPermissionTarget{}, false
-	}
-	ref, err := parseDocumentRef(docURL)
-	if err != nil {
-		return docsPermissionTarget{}, false
-	}
-	switch ref.Kind {
-	case "wiki":
-		return docsPermissionTarget{Token: ref.Token, Type: "wiki"}, true
-	case "doc", "docx":
-		return docsPermissionTarget{Token: ref.Token, Type: ref.Kind}, true
-	default:
-		return docsPermissionTarget{}, false
-	}
-}
-
-// normalizeWhiteboardResult normalizes board_tokens in the MCP response when
-// whiteboard creation markdown is detected.
-func normalizeWhiteboardResult(result map[string]interface{}, markdown string) {
-	if !isWhiteboardCreateMarkdown(markdown) {
-		return
-	}
-	result["board_tokens"] = normalizeBoardTokens(result["board_tokens"])
-}
-
-func isWhiteboardCreateMarkdown(markdown string) bool {
-	lower := strings.ToLower(markdown)
-	if strings.Contains(lower, "```mermaid") || strings.Contains(lower, "```plantuml") {
-		return true
-	}
-	return strings.Contains(lower, "<whiteboard") &&
-		(strings.Contains(lower, `type="blank"`) || strings.Contains(lower, `type='blank'`))
-}
-
-func normalizeBoardTokens(raw interface{}) []string {
-	switch v := raw.(type) {
-	case nil:
-		return []string{}
-	case []string:
-		return v
-	case []interface{}:
-		tokens := make([]string, 0, len(v))
-		for _, item := range v {
-			if s, ok := item.(string); ok && s != "" {
-				tokens = append(tokens, s)
-			}
-		}
-		return tokens
-	case string:
-		if v == "" {
-			return []string{}
-		}
-		return []string{v}
-	default:
-		return []string{}
-	}
-}
-
-// ── Shared helpers ──
-
 // concatFlags combines multiple flag slices into one.
 func concatFlags(slices ...[]common.Flag) []common.Flag {
 	var out []common.Flag
@@ -258,15 +48,3 @@ func concatFlags(slices ...[]common.Flag) []common.Flag {
 	}
 	return out
 }
-
-// buildFlagVersionMap creates a flag name → version mapping from v1 and v2 flag lists.
-func buildFlagVersionMap(v1, v2 []common.Flag) map[string]string {
-	m := make(map[string]string, len(v1)+len(v2))
-	for _, f := range v1 {
-		m[f.Name] = "v1"
-	}
-	for _, f := range v2 {
-		m[f.Name] = "v2"
-	}
-	return m
-}

shortcuts/doc/docs_create_test.go

@@ -48,7 +48,6 @@ func TestDocsCreateV2BotAutoGrantSuccess(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>项目计划</title><h1>目标</h1>",
 		"--as", "bot",
 	})
@@ -249,148 +248,63 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
 	}
 }
 
-// ── V1 (MCP) tests ──
-
-func TestDocsCreateV1BotAutoGrantSuccess(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, "ou_current_user"))
-	registerDocsCreateMCPStub(reg, map[string]interface{}{
-		"doc_id":  "doxcn_new_doc",
-		"doc_url": "https://example.feishu.cn/docx/doxcn_new_doc",
-		"message": "文档创建成功",
-	})
-
-	permStub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/permissions/doxcn_new_doc/members",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"member": map[string]interface{}{
-					"member_id":   "ou_current_user",
-					"member_type": "openid",
-					"perm":        "full_access",
-				},
-			},
-		},
-	}
-	reg.Register(permStub)
-
-	err := runDocsCreateShortcut(t, f, stdout, []string{
-		"+create",
-		"--title", "项目计划",
-		"--markdown", "## 目标",
-		"--as", "bot",
-	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeDocsCreateEnvelope(t, stdout)
-	grant, _ := data["permission_grant"].(map[string]interface{})
-	if grant["status"] != common.PermissionGrantGranted {
-		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantGranted)
-	}
-}
-
-func TestDocsCreateV1WikiSpaceAutoGrantFailure(t *testing.T) {
-	t.Parallel()
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, "ou_current_user"))
-	registerDocsCreateMCPStub(reg, map[string]interface{}{
-		"doc_id":  "doxcn_new_doc",
-		"doc_url": "https://example.feishu.cn/wiki/wikcn_new_node",
-		"message": "文档创建成功",
-	})
-
-	permStub := &httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/permissions/wikcn_new_node/members",
-		Body: map[string]interface{}{
-			"code": 230001,
-			"msg":  "no permission",
-		},
-	}
-	reg.Register(permStub)
-
-	err := runDocsCreateShortcut(t, f, stdout, []string{
-		"+create",
-		"--markdown", "## 内容",
-		"--wiki-space", "my_library",
-		"--as", "bot",
-	})
-	if err != nil {
-		t.Fatalf("document creation should still succeed when auto-grant fails, got: %v", err)
-	}
-
-	data := decodeDocsCreateEnvelope(t, stdout)
-	grant, _ := data["permission_grant"].(map[string]interface{})
-	if grant["status"] != common.PermissionGrantFailed {
-		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantFailed)
-	}
-
-	var body map[string]interface{}
-	if err := json.Unmarshal(permStub.CapturedBody, &body); err != nil {
-		t.Fatalf("failed to parse permission request body: %v", err)
-	}
-	if body["perm_type"] != "container" {
-		t.Fatalf("permission request perm_type = %#v, want %q", body["perm_type"], "container")
-	}
-}
-
-func TestDocsCreateV1FallbackURLWhenBackendOmitsIt(t *testing.T) {
+func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
-	registerDocsCreateMCPStub(reg, map[string]interface{}{
-		"doc_id":  "doxcn_new_doc",
-		"message": "文档创建成功",
-		// "doc_url" deliberately omitted to exercise the fallback.
+	registerDocsCreateAPIStub(reg, map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_new_doc",
+			"revision_id": float64(1),
+			"url":         "https://example.feishu.cn/docx/doxcn_new_doc",
+		},
 	})
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
 		"--api-version", "v1",
-		"--title", "项目计划",
-		"--markdown", "## 目标",
+		"--content", "<title>项目计划</title>",
 		"--as", "user",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-
 	data := decodeDocsCreateEnvelope(t, stdout)
-	if got, want := data["doc_url"], "https://www.feishu.cn/docx/doxcn_new_doc"; got != want {
-		t.Fatalf("doc_url = %#v, want %q (brand-standard fallback)", got, want)
+	doc, _ := data["document"].(map[string]interface{})
+	if got, want := doc["document_id"], "doxcn_new_doc"; got != want {
+		t.Fatalf("document.document_id = %#v, want %q", got, want)
 	}
 }
 
-func TestDocsCreateV1PreservesBackendDocURL(t *testing.T) {
+func TestDocsCreateRejectsLegacyV1Flags(t *testing.T) {
 	t.Parallel()
 
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
-	registerDocsCreateMCPStub(reg, map[string]interface{}{
-		"doc_id":  "doxcn_new_doc",
-		"doc_url": "https://tenant.feishu.cn/docx/doxcn_new_doc",
-		"message": "文档创建成功",
-	})
-
+	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v1",
 		"--title", "项目计划",
 		"--markdown", "## 目标",
 		"--as", "user",
 	})
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
+	if err == nil {
+		t.Fatal("expected legacy v1 flags to be rejected")
 	}
-
-	data := decodeDocsCreateEnvelope(t, stdout)
-	if got, want := data["doc_url"], "https://tenant.feishu.cn/docx/doxcn_new_doc"; got != want {
-		t.Fatalf("doc_url = %#v, want backend tenant URL %q (fallback must not overwrite)", got, want)
+	for _, want := range []string{
+		"docs +create is v2-only",
+		"the old v1 interface has been shut down",
+		"legacy v1 flag(s) --title, --markdown are no longer supported",
+		"--title -> put the title in --content",
+		"--markdown -> use --content with --doc-format markdown",
+		"lark-cli skills read lark-doc references/lark-doc-create.md",
+		"lark-cli skills read lark-doc references/lark-doc-xml.md",
+		"lark-cli skills read lark-doc references/lark-doc-md.md",
+		"follow the latest format rules",
+		"MUST NOT grep/open local SKILL.md files",
+		"lark-cli docs +create --help",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error missing %q: %v", want, err)
+		}
 	}
 }
 
@@ -421,24 +335,6 @@ func registerDocsCreateAPIStub(reg *httpmock.Registry, data map[string]interface
 	})
 }
 
-func registerDocsCreateMCPStub(reg *httpmock.Registry, result map[string]interface{}) {
-	payload, _ := json.Marshal(result)
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/mcp",
-		Body: map[string]interface{}{
-			"result": map[string]interface{}{
-				"content": []map[string]interface{}{
-					{
-						"type": "text",
-						"text": string(payload),
-					},
-				},
-			},
-		},
-	})
-}
-
 func runDocsCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, args []string) error {
 	t.Helper()
 

shortcuts/doc/docs_create_v2.go

@@ -7,25 +7,29 @@ import (
 	"context"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 // v2CreateFlags returns the flag definitions for the v2 (OpenAPI) create path.
 func v2CreateFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "content", Desc: "document content (XML or Markdown)", Hidden: true, Input: []string{common.File, common.Stdin}},
-		{Name: "doc-format", Desc: "content format (prefer XML)", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "parent-token", Desc: "parent folder or wiki-node token", Hidden: true},
-		{Name: "parent-position", Desc: "parent position (e.g. my_library)", Hidden: true},
+		{Name: "content", Desc: "document body; XML by default or Markdown when --doc-format markdown. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
+		{Name: "doc-format", Desc: "content format; xml is default and supports richer DocxXML blocks, markdown imports plain Markdown", Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "parent-token", Desc: "parent folder token or wiki node token; mutually exclusive with --parent-position"},
+		{Name: "parent-position", Desc: "parent position such as my_library; mutually exclusive with --parent-token"},
 	}
 }
 
 func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
+	if err := validateDocsV2Only(runtime, "+create", docsCreateLegacyFlags()); err != nil {
+		return err
+	}
 	if runtime.Str("content") == "" {
-		return common.FlagErrorf("--content is required")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required").WithParam("--content")
 	}
 	if runtime.Str("parent-token") != "" && runtime.Str("parent-position") != "" {
-		return common.FlagErrorf("--parent-token and --parent-position are mutually exclusive")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--parent-token and --parent-position are mutually exclusive")
 	}
 	return nil
 }

shortcuts/doc/docs_fetch.go

@@ -5,40 +5,13 @@ package doc
 
 import (
 	"context"
-	"fmt"
-	"io"
-	"strconv"
-
-	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// v1FetchFlags returns the flag definitions for the v1 (MCP) fetch path.
+// v1FetchFlags returns hidden parse-only compatibility flags for old v1 commands.
 func v1FetchFlags() []common.Flag {
-	return []common.Flag{
-		{Name: "offset", Desc: "pagination offset", Hidden: true},
-		{Name: "limit", Desc: "pagination limit", Hidden: true},
-	}
-}
-
-var docsFetchFlagVersions = buildFlagVersionMap(v1FetchFlags(), v2FetchFlags())
-
-// useV2Fetch returns true when the v2 (OpenAPI) fetch path should be used.
-// Explicit --api-version v2 takes priority; otherwise auto-detect by the
-// presence of any v2-only flag on the command line — we check pflag.Changed
-// rather than the value so that explicitly typing `--detail simple` (equal
-// to the default) still routes to v2.
-func useV2Fetch(runtime *common.RuntimeContext) bool {
-	if runtime.Str("api-version") == "v2" {
-		return true
-	}
-	for _, name := range []string{"detail", "doc-format", "scope", "revision-id", "start-block-id", "end-block-id", "keyword", "context-before", "context-after", "max-depth"} {
-		if runtime.Changed(name) {
-			return true
-		}
-	}
-	return false
+	return docsLegacyFlagDefinitions(docsFetchLegacyFlags())
 }
 
 var DocsFetch = common.Shortcut{
@@ -49,88 +22,22 @@ var DocsFetch = common.Shortcut{
 	Scopes:      []string{"docx:document:readonly"},
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
-	Tips:        docsVersionSelectionTips,
+	PostMount:   installDocsShortcutHelp("+fetch"),
 	Flags: concatFlags(
 		[]common.Flag{
-			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
+			docsAPIVersionCompatFlag(),
 			{Name: "doc", Desc: "document URL or token", Required: true},
 		},
-		v1FetchFlags(),
 		v2FetchFlags(),
+		v1FetchFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Fetch(runtime) {
-			return validateFetchV2(ctx, runtime)
-		}
-		return nil
+		return validateFetchV2(ctx, runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		if useV2Fetch(runtime) {
-			return dryRunFetchV2(ctx, runtime)
-		}
-		return dryRunFetchV1(ctx, runtime)
+		return dryRunFetchV2(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Fetch(runtime) {
-			return executeFetchV2(ctx, runtime)
-		}
-		return executeFetchV1(ctx, runtime)
-	},
-	PostMount: func(cmd *cobra.Command) {
-		installVersionedHelp(cmd, "v1", docsFetchFlagVersions)
+		return executeFetchV2(ctx, runtime)
 	},
 }
-
-// ── V1 (MCP) implementation ──
-
-func dryRunFetchV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	args := buildFetchArgsV1(runtime)
-	return common.NewDryRunAPI().
-		POST(common.MCPEndpoint(runtime.Config.Brand)).
-		Desc("MCP tool: fetch-doc").
-		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "fetch-doc", "arguments": args}}).
-		Set("mcp_tool", "fetch-doc").Set("args", args)
-}
-
-func executeFetchV1(_ context.Context, runtime *common.RuntimeContext) error {
-	warnDeprecatedV1(runtime, "+fetch")
-	args := buildFetchArgsV1(runtime)
-
-	result, err := common.CallMCPTool(runtime, "fetch-doc", args)
-	if err != nil {
-		return err
-	}
-
-	if md, ok := result["markdown"].(string); ok {
-		result["markdown"] = fixExportedMarkdown(md)
-	}
-
-	runtime.OutFormat(result, nil, func(w io.Writer) {
-		if title, ok := result["title"].(string); ok && title != "" {
-			fmt.Fprintf(w, "# %s\n\n", title)
-		}
-		if md, ok := result["markdown"].(string); ok {
-			fmt.Fprintln(w, md)
-		}
-		if hasMore, ok := result["has_more"].(bool); ok && hasMore {
-			fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---")
-		}
-	})
-	return nil
-}
-
-func buildFetchArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
-	args := map[string]interface{}{
-		"doc_id":           runtime.Str("doc"),
-		"skip_task_detail": true,
-	}
-	if v := runtime.Str("offset"); v != "" {
-		n, _ := strconv.Atoi(v)
-		args["offset"] = n
-	}
-	if v := runtime.Str("limit"); v != "" {
-		n, _ := strconv.Atoi(v)
-		args["limit"] = n
-	}
-	return args
-}

shortcuts/doc/docs_fetch_v2.go

@@ -10,22 +10,23 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 // v2FetchFlags returns the flag definitions for the v2 (OpenAPI) fetch path.
 func v2FetchFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "doc-format", Desc: "content format", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "detail", Desc: "export detail level: simple (read-only) | with-ids (block IDs for cross-referencing) | full (all attrs for editing)", Hidden: true, Default: "simple", Enum: []string{"simple", "with-ids", "full"}},
-		{Name: "revision-id", Desc: "document revision (-1 = latest)", Hidden: true, Type: "int", Default: "-1"},
-		{Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
-		{Name: "start-block-id", Desc: "range/section mode: start (anchor) block id"},
-		{Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document"},
-		{Name: "keyword", Desc: "keyword mode: substring + regex match (case-insensitive); use '|' for OR branches, e.g. 'foo|bar' or 'bug|缺陷'"},
-		{Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Type: "int", Default: "0"},
-		{Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Type: "int", Default: "0"},
-		{Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Type: "int", Default: "-1"},
+		{Name: "doc-format", Desc: "output content format; xml keeps DocxXML structure and optional block ids, markdown is plain export", Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "detail", Desc: "detail level; simple for reading, with-ids for block references, full for styles and edit metadata", Default: "simple", Enum: []string{"simple", "with-ids", "full"}},
+		{Name: "revision-id", Desc: "document revision id; -1 means latest", Type: "int", Default: "-1"},
+		{Name: "scope", Desc: "read scope; full reads whole doc, outline lists headings, section expands from heading anchor, range uses block ids, keyword searches text", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
+		{Name: "start-block-id", Desc: "range/section anchor block id; required for section and optional start for range"},
+		{Name: "end-block-id", Desc: "range end block id; -1 means through document end"},
+		{Name: "keyword", Desc: "keyword scope query; supports case-insensitive substring/regex fallback and '|' OR branches, e.g. foo|bar or bug|缺陷"},
+		{Name: "context-before", Desc: "range/keyword/section context: sibling blocks before selected top-level blocks", Type: "int", Default: "0"},
+		{Name: "context-after", Desc: "range/keyword/section context: sibling blocks after selected top-level blocks", Type: "int", Default: "0"},
+		{Name: "max-depth", Desc: "outline heading level cap; other scopes subtree depth where -1 is unlimited and 0 is block only", Type: "int", Default: "-1"},
 	}
 }
 
@@ -33,8 +34,11 @@ func v2FetchFlags() []common.Flag {
 // --dry-run so that invalid input fails with a structured exit code (2) and
 // JSON envelope instead of slipping through dry-run as a "success".
 func validateFetchV2(_ context.Context, runtime *common.RuntimeContext) error {
+	if err := validateDocsV2Only(runtime, "+fetch", docsFetchLegacyFlags()); err != nil {
+		return err
+	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
-		return common.FlagErrorf("invalid --doc: %v", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc: %v", err).WithParam("--doc")
 	}
 	if err := validateFetchDetail(runtime); err != nil {
 		return err
@@ -150,7 +154,7 @@ func validateFetchDetail(runtime *common.RuntimeContext) error {
 		return nil
 	}
 	if detail == "with-ids" || detail == "full" {
-		return common.FlagErrorf("--detail %s is only supported with --doc-format xml; %s output has no block ids, use --detail simple or switch to --doc-format xml", detail, format)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--detail %s is only supported with --doc-format xml; %s output has no block ids, use --detail simple or switch to --doc-format xml", detail, format).WithParam("--detail")
 	}
 	return nil
 }
@@ -163,13 +167,13 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 	}
 
 	if v := runtime.Int("context-before"); v < 0 {
-		return common.FlagErrorf("--context-before must be >= 0, got %d", v)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--context-before must be >= 0, got %d", v).WithParam("--context-before")
 	}
 	if v := runtime.Int("context-after"); v < 0 {
-		return common.FlagErrorf("--context-after must be >= 0, got %d", v)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--context-after must be >= 0, got %d", v).WithParam("--context-after")
 	}
 	if v := runtime.Int("max-depth"); v < -1 {
-		return common.FlagErrorf("--max-depth must be >= -1, got %d", v)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--max-depth must be >= -1, got %d", v).WithParam("--max-depth")
 	}
 
 	switch mode {
@@ -178,20 +182,20 @@ func validateReadModeFlags(runtime *common.RuntimeContext) error {
 	case "range":
 		if strings.TrimSpace(runtime.Str("start-block-id")) == "" &&
 			strings.TrimSpace(runtime.Str("end-block-id")) == "" {
-			return common.FlagErrorf("range mode requires --start-block-id or --end-block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "range mode requires --start-block-id or --end-block-id")
 		}
 		return nil
 	case "keyword":
 		if strings.TrimSpace(runtime.Str("keyword")) == "" {
-			return common.FlagErrorf("keyword mode requires --keyword")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "keyword mode requires --keyword").WithParam("--keyword")
 		}
 		return nil
 	case "section":
 		if strings.TrimSpace(runtime.Str("start-block-id")) == "" {
-			return common.FlagErrorf("section mode requires --start-block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "section mode requires --start-block-id").WithParam("--start-block-id")
 		}
 		return nil
 	default:
-		return common.FlagErrorf("invalid --scope %q", mode)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --scope %q", mode).WithParam("--scope")
 	}
 }

shortcuts/doc/docs_fetch_v2_test.go

@@ -5,6 +5,7 @@ package doc
 
 import (
 	"context"
+	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/shortcuts/common"
@@ -58,6 +59,82 @@ func TestBuildFetchBodyOmitsEmptyScene(t *testing.T) {
 	}
 }
 
+func TestDocsFetchDryRunDefaultsToV2Endpoint(t *testing.T) {
+	t.Parallel()
+
+	runtime := newFetchShortcutTestRuntime(t, "", nil)
+	if err := validateFetchV2(context.Background(), runtime); err != nil {
+		t.Fatalf("validateFetchV2() error = %v", err)
+	}
+
+	dry := decodeDocDryRun(t, DocsFetch.DryRun(context.Background(), runtime))
+	if len(dry.API) != 1 {
+		t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
+	}
+	if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnFetchDryRun/fetch"; got != want {
+		t.Fatalf("dry-run URL = %q, want %q", got, want)
+	}
+	if got, want := dry.API[0].Body["format"], "xml"; got != want {
+		t.Fatalf("dry-run format = %#v, want %q", got, want)
+	}
+}
+
+func TestDocsFetchAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
+	t.Parallel()
+
+	runtime := newFetchShortcutTestRuntime(t, "v1", nil)
+	if err := validateFetchV2(context.Background(), runtime); err != nil {
+		t.Fatalf("validateFetchV2() error = %v", err)
+	}
+
+	dry := decodeDocDryRun(t, DocsFetch.DryRun(context.Background(), runtime))
+	if len(dry.API) != 1 {
+		t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
+	}
+	if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnFetchDryRun/fetch"; got != want {
+		t.Fatalf("dry-run URL = %q, want %q", got, want)
+	}
+}
+
+func TestDocsFetchRejectsLegacyFlags(t *testing.T) {
+	tests := []struct {
+		name     string
+		setFlags map[string]string
+		want     []string
+	}{
+		{
+			name:     "legacy offset",
+			setFlags: map[string]string{"offset": "10"},
+			want: []string{
+				"docs +fetch is v2-only",
+				"the old v1 interface has been shut down",
+				"legacy v1 flag(s) --offset are no longer supported",
+				"--offset -> use --scope outline/range/keyword/section",
+				"lark-cli skills read lark-doc references/lark-doc-fetch.md",
+				"MUST NOT grep/open local SKILL.md files",
+				"lark-cli docs +fetch --help",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newFetchShortcutTestRuntime(t, "", tt.setFlags)
+			err := validateFetchV2(context.Background(), runtime)
+			if err == nil {
+				t.Fatal("expected v2-only validation error")
+			}
+			for _, want := range tt.want {
+				if !strings.Contains(err.Error(), want) {
+					t.Fatalf("error missing %q: %v", want, err)
+				}
+			}
+		})
+	}
+}
+
 func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+fetch"}
 	cmd.Flags().String("doc-format", "xml", "")
@@ -73,6 +150,37 @@ func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
 }
 
+func newFetchShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[string]string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "+fetch"}
+	cmd.Flags().String("api-version", "", "")
+	cmd.Flags().String("doc", "doxcnFetchDryRun", "")
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("detail", "simple", "")
+	cmd.Flags().Int("revision-id", -1, "")
+	cmd.Flags().String("scope", "full", "")
+	cmd.Flags().String("start-block-id", "", "")
+	cmd.Flags().String("end-block-id", "", "")
+	cmd.Flags().String("keyword", "", "")
+	cmd.Flags().Int("context-before", 0, "")
+	cmd.Flags().Int("context-after", 0, "")
+	cmd.Flags().Int("max-depth", -1, "")
+	cmd.Flags().String("offset", "", "")
+	cmd.Flags().String("limit", "", "")
+	if apiVersion != "" {
+		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
+			t.Fatalf("set api-version: %v", err)
+		}
+	}
+	for name, value := range setFlags {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set %s: %v", name, err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, nil)
+}
+
 func newCreateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+create"}
 	cmd.Flags().String("doc-format", "xml", "")

shortcuts/doc/docs_search.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -58,7 +59,7 @@ var DocsSearch = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPI("POST", "/open-apis/search/v2/doc_wiki/search", nil, requestData)
+		data, err := runtime.CallAPITyped("POST", "/open-apis/search/v2/doc_wiki/search", nil, requestData)
 		if err != nil {
 			return err
 		}
@@ -159,7 +160,7 @@ func buildDocsSearchRequest(query, filterStr, pageToken, pageSizeStr string) (ma
 
 	var filter map[string]interface{}
 	if err := json.Unmarshal([]byte(filterStr), &filter); err != nil {
-		return nil, output.ErrValidation("--filter is not valid JSON")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--filter is not valid JSON").WithParam("--filter")
 	}
 	if err := convertTimeRangeInFilter(filter, "open_time"); err != nil {
 		return nil, err
@@ -172,7 +173,7 @@ func buildDocsSearchRequest(query, filterStr, pageToken, pageSizeStr string) (ma
 	hasSpaceIDs := hasNonEmptyFilterArray(filter, "space_ids")
 
 	if hasFolderTokens && hasSpaceIDs {
-		return nil, output.ErrValidation("--filter cannot contain both folder_tokens and space_ids; doc and wiki scoped search cannot be combined")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--filter cannot contain both folder_tokens and space_ids; doc and wiki scoped search cannot be combined").WithParam("--filter")
 	}
 
 	docFilter := cloneFilterMap(filter)
@@ -225,14 +226,14 @@ func convertTimeRangeInFilter(filter map[string]interface{}, key string) error {
 	if start, ok := rangeMap["start"].(string); ok && start != "" {
 		startTime, err := toUnixSeconds(start)
 		if err != nil {
-			return output.ErrValidation("invalid %s.start %q: %s", key, start, err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s.start %q: %s", key, start, err).WithParam("--filter")
 		}
 		result["start"] = startTime
 	}
 	if end, ok := rangeMap["end"].(string); ok && end != "" {
 		endTime, err := toUnixSeconds(end)
 		if err != nil {
-			return output.ErrValidation("invalid %s.end %q: %s", key, end, err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid %s.end %q: %s", key, end, err).WithParam("--filter")
 		}
 		result["end"] = endTime
 	}
@@ -256,7 +257,7 @@ func toUnixSeconds(input string) (int64, error) {
 	if n, err := strconv.ParseInt(input, 10, 64); err == nil {
 		return n, nil
 	}
-	return 0, fmt.Errorf("expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds")
+	return 0, fmt.Errorf("expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds") //nolint:forbidigo // intermediate parse helper; caller wraps into typed ValidationError
 }
 
 func unixTimestampToISO8601(v interface{}) string {

shortcuts/doc/docs_update.go

@@ -5,57 +5,13 @@ package doc
 
 import (
 	"context"
-	"fmt"
-	"regexp"
-	"strings"
-
-	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-var validModesV1 = map[string]bool{
-	"append":        true,
-	"overwrite":     true,
-	"replace_range": true,
-	"replace_all":   true,
-	"insert_before": true,
-	"insert_after":  true,
-	"delete_range":  true,
-}
-
-var needsSelectionV1 = map[string]bool{
-	"replace_range": true,
-	"replace_all":   true,
-	"insert_before": true,
-	"insert_after":  true,
-	"delete_range":  true,
-}
-
-// v1UpdateFlags returns the flag definitions for the v1 (MCP) update path.
+// v1UpdateFlags returns hidden parse-only compatibility flags for old v1 commands.
 func v1UpdateFlags() []common.Flag {
-	return []common.Flag{
-		{Name: "mode", Desc: "update mode: append | overwrite | replace_range | replace_all | insert_before | insert_after | delete_range", Hidden: true},
-		{Name: "markdown", Desc: "new content (Lark-flavored Markdown; create blank whiteboards with <whiteboard type=\"blank\"></whiteboard>, repeat to create multiple boards)", Hidden: true, Input: []string{common.File, common.Stdin}},
-		{Name: "selection-with-ellipsis", Desc: "content locator (e.g. 'start...end')", Hidden: true},
-		{Name: "selection-by-title", Desc: "title locator (e.g. '## Section')", Hidden: true},
-		{Name: "new-title", Desc: "also update document title", Hidden: true},
-	}
-}
-
-var docsUpdateFlagVersions = buildFlagVersionMap(v1UpdateFlags(), v2UpdateFlags())
-
-// useV2Update returns true when the v2 (OpenAPI) update path should be used.
-// Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags.
-func useV2Update(runtime *common.RuntimeContext) bool {
-	if runtime.Str("api-version") == "v2" {
-		return true
-	}
-	return runtime.Str("command") != "" ||
-		runtime.Str("content") != "" ||
-		runtime.Str("pattern") != "" ||
-		runtime.Str("block-id") != "" ||
-		runtime.Str("src-block-ids") != ""
+	return docsLegacyFlagDefinitions(docsUpdateLegacyFlags())
 }
 
 var DocsUpdate = common.Shortcut{
@@ -65,225 +21,22 @@ var DocsUpdate = common.Shortcut{
 	Risk:        "write",
 	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
 	AuthTypes:   []string{"user", "bot"},
-	Tips:        docsVersionSelectionTips,
+	PostMount:   installDocsShortcutHelp("+update"),
 	Flags: concatFlags(
 		[]common.Flag{
-			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
+			docsAPIVersionCompatFlag(),
 			{Name: "doc", Desc: "document URL or token", Required: true},
 		},
-		v1UpdateFlags(),
 		v2UpdateFlags(),
+		v1UpdateFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Update(runtime) {
-			return validateUpdateV2(ctx, runtime)
-		}
-		return validateUpdateV1(ctx, runtime)
+		return validateUpdateV2(ctx, runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		if useV2Update(runtime) {
-			return dryRunUpdateV2(ctx, runtime)
-		}
-		return dryRunUpdateV1(ctx, runtime)
+		return dryRunUpdateV2(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if useV2Update(runtime) {
-			return executeUpdateV2(ctx, runtime)
-		}
-		return executeUpdateV1(ctx, runtime)
-	},
-	PostMount: func(cmd *cobra.Command) {
-		installVersionedHelp(cmd, "v1", docsUpdateFlagVersions)
+		return executeUpdateV2(ctx, runtime)
 	},
 }
-
-// ── V1 (MCP) implementation ──
-
-func validateUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
-	mode := runtime.Str("mode")
-	if mode == "" {
-		return common.FlagErrorf("--mode is required")
-	}
-	if !validModesV1[mode] {
-		return common.FlagErrorf("invalid --mode %q, valid: append | overwrite | replace_range | replace_all | insert_before | insert_after | delete_range", mode)
-	}
-
-	if mode != "delete_range" && runtime.Str("markdown") == "" {
-		return common.FlagErrorf("--%s mode requires --markdown", mode)
-	}
-
-	selEllipsis := runtime.Str("selection-with-ellipsis")
-	selTitle := runtime.Str("selection-by-title")
-	if selEllipsis != "" && selTitle != "" {
-		return common.FlagErrorf("--selection-with-ellipsis and --selection-by-title are mutually exclusive")
-	}
-
-	if needsSelectionV1[mode] && selEllipsis == "" && selTitle == "" {
-		return common.FlagErrorf(selectionRequiredMessageV1(mode))
-	}
-	if err := validateSelectionByTitleV1(selTitle); err != nil {
-		return err
-	}
-
-	return nil
-}
-
-func selectionRequiredMessageV1(mode string) string {
-	msg := fmt.Sprintf("--%s mode requires --selection-with-ellipsis or --selection-by-title", mode)
-	if mode == "replace_all" {
-		msg += ". If you intended to replace the entire document body, use --mode overwrite instead."
-	}
-	return msg
-}
-
-func validateSelectionByTitleV1(title string) error {
-	if title == "" {
-		return nil
-	}
-	trimmed := strings.TrimSpace(title)
-	if strings.Contains(trimmed, "\n") || strings.Contains(trimmed, "\r") {
-		return common.FlagErrorf("--selection-by-title must be a single heading line (for example: '## Section')")
-	}
-	if strings.HasPrefix(trimmed, "#") {
-		return nil
-	}
-	return common.FlagErrorf("--selection-by-title must include markdown heading prefix '#'. Example: --selection-by-title '## Section'")
-}
-
-func dryRunUpdateV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	args := buildUpdateArgsV1(runtime)
-	return common.NewDryRunAPI().
-		POST(common.MCPEndpoint(runtime.Config.Brand)).
-		Desc("MCP tool: update-doc").
-		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "update-doc", "arguments": args}}).
-		Set("mcp_tool", "update-doc").Set("args", args)
-}
-
-func executeUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
-	warnDeprecatedV1(runtime, "+update")
-
-	// Static semantic checks run before the MCP call so users see
-	// warnings even if the subsequent request fails. They never block
-	// execution — the update still proceeds.
-	for _, w := range docsUpdateWarnings(runtime.Str("mode"), runtime.Str("markdown")) {
-		fmt.Fprintf(runtime.IO().ErrOut, "warning: %s\n", w)
-	}
-
-	// Overwrite replaces the entire document, silently discarding any
-	// whiteboard or file-attachment blocks that cannot be re-created from
-	// Markdown. Pre-fetch the current content and warn when such blocks
-	// are present so the caller can take a backup before proceeding.
-	if runtime.Str("mode") == "overwrite" {
-		if w := warnOverwriteResourceBlocks(runtime); w != "" {
-			fmt.Fprintf(runtime.IO().ErrOut, "warning: %s\n", w)
-		}
-	}
-
-	// Surface callout type= hint so users know to switch to background-color/
-	// border-color when they want a colored callout. Non-blocking, advisory.
-	if md := runtime.Str("markdown"); md != "" {
-		WarnCalloutType(md, runtime.IO().ErrOut)
-	}
-
-	args := buildUpdateArgsV1(runtime)
-
-	result, err := common.CallMCPTool(runtime, "update-doc", args)
-	if err != nil {
-		return err
-	}
-
-	normalizeWhiteboardResult(result, runtime.Str("markdown"))
-	runtime.Out(result, nil)
-	return nil
-}
-
-func buildUpdateArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
-	args := map[string]interface{}{
-		"doc_id": runtime.Str("doc"),
-		"mode":   runtime.Str("mode"),
-	}
-	if v := runtime.Str("markdown"); v != "" {
-		args["markdown"] = v
-	}
-	if v := runtime.Str("selection-with-ellipsis"); v != "" {
-		args["selection_with_ellipsis"] = v
-	}
-	if v := runtime.Str("selection-by-title"); v != "" {
-		args["selection_by_title"] = v
-	}
-	if v := runtime.Str("new-title"); v != "" {
-		args["new_title"] = v
-	}
-	return args
-}
-
-// resourceBlockRe matches the opening of a <whiteboard …> or <file …> tag
-// (followed by whitespace, > or /) to avoid false positives on tag names like
-// <file-view> or prose that merely mentions the word "whiteboard".
-var resourceBlockRe = regexp.MustCompile(`<(whiteboard|file)[\s/>]`)
-
-// warnOverwriteResourceBlocks pre-fetches the current document and returns a
-// non-empty warning string when the document contains whiteboard or file
-// attachment blocks that would be permanently deleted by an overwrite. Returns
-// an empty string (no warning) when the document is clean or the fetch fails
-// (we never block the overwrite on a best-effort check).
-//
-// This function is not unit-tested because it depends on an external MCP call
-// (fetch-doc). The pure detection logic lives in checkOverwriteResourceBlocks,
-// which has full table-driven coverage.
-//
-// Performance: this adds one extra fetch-doc round-trip to every --mode overwrite
-// call, even when the document has no resource blocks. The cost is intentional:
-// the guard is best-effort and silent on failure, so the latency is bounded and
-// the trade-off is acceptable to avoid silent data loss.
-func warnOverwriteResourceBlocks(runtime *common.RuntimeContext) string {
-	args := map[string]interface{}{
-		"doc_id": runtime.Str("doc"),
-		// skip_task_detail reduces response payload by omitting per-block task
-		// metadata, making the pre-fetch faster and cheaper.
-		"skip_task_detail": true,
-	}
-	result, err := common.CallMCPTool(runtime, "fetch-doc", args)
-	if err != nil {
-		// Fetch failed — silently skip the guard rather than blocking overwrite.
-		return ""
-	}
-	md, _ := result["markdown"].(string)
-	return checkOverwriteResourceBlocks(md)
-}
-
-// checkOverwriteResourceBlocks scans Markdown for resource block tags that
-// cannot survive an overwrite: <whiteboard …> and <file …>. Returns a
-// warning string listing the counts if any are found, empty string otherwise.
-func checkOverwriteResourceBlocks(markdown string) string {
-	matches := resourceBlockRe.FindAllStringSubmatch(markdown, -1)
-	whiteboards, files := 0, 0
-	for _, m := range matches {
-		switch m[1] {
-		case "whiteboard":
-			whiteboards++
-		case "file":
-			files++
-		}
-	}
-	var found []string
-	if whiteboards == 1 {
-		found = append(found, "1 whiteboard block")
-	} else if whiteboards > 1 {
-		found = append(found, fmt.Sprintf("%d whiteboard blocks", whiteboards))
-	}
-	if files == 1 {
-		found = append(found, "1 file attachment block")
-	} else if files > 1 {
-		found = append(found, fmt.Sprintf("%d file attachment blocks", files))
-	}
-	if len(found) == 0 {
-		return ""
-	}
-	return fmt.Sprintf(
-		"the document contains %s that cannot be reconstructed from Markdown; "+
-			"overwrite will permanently delete them. "+
-			"Consider fetching a backup with `docs +fetch` before overwriting.",
-		strings.Join(found, " and "),
-	)
-}

shortcuts/doc/docs_update_check.go

@@ -1,281 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"regexp"
-	"strings"
-)
-
-// docsUpdateWarnings returns a list of human-readable warnings for a
-// `docs +update` invocation based on static analysis of the mode and
-// Markdown payload. The warnings describe CLI/MCP contract edges that
-// commonly surprise users; the update is still executed — callers
-// decide whether to stop at a warning.
-//
-// Both checks ignore fenced code blocks (```…``` and ~~~…~~~, with up
-// to 3 leading spaces per CommonMark §4.5), inline code spans, and
-// backslash-escaped emphasis markers so that literal Markdown content
-// embedded in code samples or escaped prose does not produce false
-// positives.
-//
-// Warnings emitted (current):
-//
-//  1. replace_* modes do not split blocks. A Markdown payload containing
-//     a blank line (\n\n) in prose implies the caller expects multiple
-//     paragraphs, but replace_range / replace_all only swap in-block
-//     text. The resulting block will contain the blank line as literal
-//     text and appear as a single paragraph in the UI.
-//
-//  2. Lark does not round-trip bold+italic. Six shapes are detected:
-//     ***text***   ___text___
-//     **_text_**   __*text*__
-//     _**text**_   *__text__*
-//     Lark stores only one of the two emphases (usually italic), silently
-//     dropping the other. The user wanted both; they will get one.
-func docsUpdateWarnings(mode, markdown string) []string {
-	var warnings []string
-	if w := checkDocsUpdateReplaceMultilineMarkdown(mode, markdown); w != "" {
-		warnings = append(warnings, w)
-	}
-	if w := checkDocsUpdateBoldItalic(markdown); w != "" {
-		warnings = append(warnings, w)
-	}
-	return warnings
-}
-
-// checkDocsUpdateReplaceMultilineMarkdown flags markdown that contains a
-// blank-line paragraph break outside fenced code blocks under a replace_*
-// mode. Blank lines inside code fences are literal content and don't
-// imply paragraph semantics, so they are deliberately ignored.
-func checkDocsUpdateReplaceMultilineMarkdown(mode, markdown string) string {
-	if mode != "replace_range" && mode != "replace_all" {
-		return ""
-	}
-	// A CR/LF-robust check: both "\n\n" and "\r\n\r\n" count as paragraph
-	// separators. We normalize line endings once before detection.
-	normalized := strings.ReplaceAll(markdown, "\r\n", "\n")
-	if !proseHasBlankLine(normalized) {
-		return ""
-	}
-	return "--mode=" + mode + " does not split a block into multiple paragraphs; " +
-		"the blank line in --markdown will render as literal text. " +
-		"For multiple paragraphs, use --mode=delete_range followed by --mode=insert_before."
-}
-
-// combinedEmphasisPatterns holds the six documented combined-emphasis shapes
-// that Lark downgrades to a single emphasis. Each entry pairs a regex with a
-// short shape label for the warning message. The two forms per shape (with
-// and without `[^…]*?`) are there because the lazy quantifier needs at least
-// one non-delimiter character to match; single-rune payloads (e.g. `***X***`)
-// take the second alternation.
-var combinedEmphasisPatterns = []struct {
-	shape string
-	re    *regexp.Regexp
-}{
-	// Bold+italic with a single delimiter char.
-	{"***text***", regexp.MustCompile(`\*\*\*\S[^*]*?\S\*\*\*|\*\*\*\S\*\*\*`)},
-	{"___text___", regexp.MustCompile(`___\S[^_]*?\S___|___\S___`)},
-
-	// Bold wrapping italic (asterisk outside).
-	{"**_text_**", regexp.MustCompile(`\*\*_\S[^_*]*?\S_\*\*|\*\*_\S_\*\*`)},
-	{"__*text*__", regexp.MustCompile(`__\*\S[^_*]*?\S\*__|__\*\S\*__`)},
-
-	// Italic wrapping bold (asterisk inside).
-	{"_**text**_", regexp.MustCompile(`_\*\*\S[^_*]*?\S\*\*_|_\*\*\S\*\*_`)},
-	{"*__text__*", regexp.MustCompile(`\*__\S[^_*]*?\S__\*|\*__\S__\*`)},
-}
-
-// checkDocsUpdateBoldItalic flags Markdown emphases that attempt to
-// combine bold and italic in a way Lark cannot represent. Fenced code
-// blocks, inline code spans, and backslash-escaped emphasis markers are
-// stripped first so that literal markdown examples ("here is a
-// `***keyword***` to flag") do not trigger the warning.
-func checkDocsUpdateBoldItalic(markdown string) string {
-	if markdown == "" {
-		return ""
-	}
-	sanitized := stripEscapedEmphasisMarkers(stripMarkdownCodeRegions(markdown))
-	for _, p := range combinedEmphasisPatterns {
-		if p.re.MatchString(sanitized) {
-			return "Lark does not support combined bold+italic markers " +
-				"(e.g. ***text***, ___text___, **_text_**, _**text**_, __*text*__, *__text__*); " +
-				"the emphasis will be downgraded to either bold or italic. " +
-				"Split into two separate emphases or drop one of them."
-		}
-	}
-	return ""
-}
-
-// proseHasBlankLine reports whether markdown contains a blank line outside
-// of fenced code blocks. Blank lines inside ```...``` or ~~~...~~~ fences
-// are code content, not paragraph separators, and must not trip the
-// "replace_* cannot split paragraphs" warning.
-//
-// A blank line counts only when it sits between two non-blank boundaries
-// (other prose, or a fence open/close). A trailing empty line at EOF is
-// not treated as "\n\n".
-func proseHasBlankLine(markdown string) bool {
-	lines := strings.Split(markdown, "\n")
-	inFence := false
-	var fenceMarker string
-	for i, line := range lines {
-		if inFence {
-			if isCodeFenceClose(line, fenceMarker) {
-				inFence = false
-				fenceMarker = ""
-			}
-			continue
-		}
-		if marker := codeFenceOpenMarker(line); marker != "" {
-			inFence = true
-			fenceMarker = marker
-			continue
-		}
-		if strings.TrimSpace(line) == "" && i > 0 && i+1 < len(lines) {
-			return true
-		}
-	}
-	return false
-}
-
-// stripMarkdownCodeRegions returns markdown with fenced code blocks blanked
-// out and inline code spans replaced by whitespace of equivalent length.
-// Byte offsets outside the masked regions are preserved, so follow-on
-// regex matches still point at real prose positions.
-func stripMarkdownCodeRegions(markdown string) string {
-	lines := strings.Split(markdown, "\n")
-	inFence := false
-	var fenceMarker string
-	for i, line := range lines {
-		if inFence {
-			if isCodeFenceClose(line, fenceMarker) {
-				inFence = false
-				fenceMarker = ""
-			}
-			lines[i] = ""
-			continue
-		}
-		if marker := codeFenceOpenMarker(line); marker != "" {
-			inFence = true
-			fenceMarker = marker
-			lines[i] = ""
-			continue
-		}
-		lines[i] = maskInlineCodeSpans(line)
-	}
-	return strings.Join(lines, "\n")
-}
-
-// maskInlineCodeSpans replaces the byte ranges of any inline code spans in
-// line with space characters of equal length. Uses scanInlineCodeSpans from
-// markdown_fix.go, which implements the CommonMark §6.1 matching-backtick-run
-// rule (so “ `a`b` “ is a single span).
-func maskInlineCodeSpans(line string) string {
-	spans := scanInlineCodeSpans(line)
-	if len(spans) == 0 {
-		return line
-	}
-	var sb strings.Builder
-	pos := 0
-	for _, loc := range spans {
-		sb.WriteString(line[pos:loc[0]])
-		sb.WriteString(strings.Repeat(" ", loc[1]-loc[0]))
-		pos = loc[1]
-	}
-	sb.WriteString(line[pos:])
-	return sb.String()
-}
-
-// stripEscapedEmphasisMarkers removes backslash-escaped '*' and '_' so the
-// bold/italic regexes don't treat literal sequences like `\***text***` as
-// real combined emphasis. CommonMark renders "\*" as a literal "*" with no
-// emphasis semantics; dropping the escape + its target from the detection
-// input keeps the heuristic aligned with what the renderer actually does.
-//
-// Known limitation: a doubled backslash escape ("\\" followed by a real
-// emphasis marker, e.g. `\\***text***`) renders as a literal backslash
-// followed by genuine combined emphasis, but this strip is not a proper
-// parser and will instead consume the second backslash as the opener for
-// another escape. That hides the real emphasis from the check, producing
-// a false negative. Practical impact is small (this shape is rare in the
-// kind of AI-Agent prompts we target) and the alternative — a full
-// CommonMark escape parser — is not worth the code surface here.
-func stripEscapedEmphasisMarkers(s string) string {
-	s = strings.ReplaceAll(s, `\*`, "")
-	s = strings.ReplaceAll(s, `\_`, "")
-	return s
-}
-
-// codeFenceOpenMarker returns the fence marker (e.g. "```" or "~~~~") if
-// line opens a fenced code block, otherwise "". Applies CommonMark §4.5
-// rules: up to 3 leading spaces are tolerated; 4+ leading spaces (or any
-// leading tab, which expands to 4 columns) make the line an indented code
-// block rather than a fence.
-func codeFenceOpenMarker(line string) string {
-	body, ok := fenceIndentOK(line)
-	if !ok {
-		return ""
-	}
-	switch {
-	case strings.HasPrefix(body, "```"):
-		return leadingRun(body, '`')
-	case strings.HasPrefix(body, "~~~"):
-		return leadingRun(body, '~')
-	}
-	return ""
-}
-
-// isCodeFenceClose reports whether line closes a fence opened with marker.
-// Per CommonMark §4.5 the closer must use the same fence character, be at
-// least as long as the opener, sit within 0..3 leading spaces, and carry
-// no info-string text.
-func isCodeFenceClose(line, marker string) bool {
-	if marker == "" {
-		return false
-	}
-	body, ok := fenceIndentOK(line)
-	if !ok {
-		return false
-	}
-	fenceChar := marker[0]
-	run := leadingRun(body, fenceChar)
-	if len(run) < len(marker) {
-		return false
-	}
-	return strings.TrimSpace(body[len(run):]) == ""
-}
-
-// fenceIndentOK returns (bodyWithoutLeadingSpaces, true) when line has
-// 0..3 leading spaces and no leading tab — i.e. the indentation is
-// permissible for a CommonMark fence. Returns ("", false) otherwise
-// (4+ leading spaces or any tab), meaning the line must be treated as
-// indented code block content rather than a fence boundary.
-func fenceIndentOK(line string) (string, bool) {
-	for i := 0; i < len(line) && i < 4; i++ {
-		switch line[i] {
-		case ' ':
-			continue
-		case '\t':
-			return "", false
-		default:
-			return line[i:], true
-		}
-	}
-	// Reached index 4 without hitting a non-space character: too indented.
-	if len(line) >= 4 {
-		return "", false
-	}
-	// Line shorter than 4 chars and all spaces — still valid (empty content).
-	return "", true
-}
-
-// leadingRun returns the longest prefix of s made up of the byte c.
-func leadingRun(s string, c byte) string {
-	i := 0
-	for i < len(s) && s[i] == c {
-		i++
-	}
-	return s[:i]
-}

shortcuts/doc/docs_update_check_test.go

@@ -1,375 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestCheckDocsUpdateReplaceMultilineMarkdown(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		mode     string
-		markdown string
-		wantHint bool
-	}{
-		{
-			name:     "replace_range with blank line emits hint",
-			mode:     "replace_range",
-			markdown: "new paragraph\n\nsecond paragraph",
-			wantHint: true,
-		},
-		{
-			name:     "replace_all with blank line emits hint",
-			mode:     "replace_all",
-			markdown: "first\n\nsecond",
-			wantHint: true,
-		},
-		{
-			name:     "replace_range single paragraph is fine",
-			mode:     "replace_range",
-			markdown: "just a single paragraph of text",
-			wantHint: false,
-		},
-		{
-			name:     "single newline is not a paragraph break",
-			mode:     "replace_range",
-			markdown: "line one\nline two",
-			wantHint: false,
-		},
-		{
-			name:     "crlf paragraph break is also detected",
-			mode:     "replace_range",
-			markdown: "first\r\n\r\nsecond",
-			wantHint: true,
-		},
-		{
-			name:     "other modes are not flagged",
-			mode:     "insert_before",
-			markdown: "first\n\nsecond",
-			wantHint: false,
-		},
-		{
-			name:     "append mode is not flagged",
-			mode:     "append",
-			markdown: "first\n\nsecond",
-			wantHint: false,
-		},
-		{
-			name:     "empty markdown is fine",
-			mode:     "replace_range",
-			markdown: "",
-			wantHint: false,
-		},
-		{
-			// The check must ignore blank lines inside fenced code; otherwise
-			// a user replacing one block with a legitimate code sample that
-			// contains blank lines would see a spurious warning.
-			name:     "blank line inside backtick fenced code is not flagged",
-			mode:     "replace_range",
-			markdown: "```\nline1\n\nline2\n```",
-			wantHint: false,
-		},
-		{
-			name:     "blank line inside tilde fenced code is not flagged",
-			mode:     "replace_range",
-			markdown: "~~~\ncode line one\n\ncode line two\n~~~",
-			wantHint: false,
-		},
-		{
-			// Mixed prose + fenced code: any blank line in prose still wins,
-			// even if the fenced content also contains blanks.
-			name:     "blank line in prose outside fence still flags even when fence has blanks",
-			mode:     "replace_range",
-			markdown: "first paragraph\n\nsecond paragraph\n\n```\ncode\n\nmore\n```",
-			wantHint: true,
-		},
-		{
-			// Fenced code with no blank lines inside must not trip on the
-			// fence markers themselves.
-			name:     "fenced code with no blank lines does not flag",
-			mode:     "replace_range",
-			markdown: "prose before\n```go\nfmt.Println(\"hi\")\n```\nprose after",
-			wantHint: false,
-		},
-		{
-			// CommonMark §4.5: the closing fence must be ≥ opening fence length.
-			// A 4-backtick close for a 3-backtick open is a legitimate way to
-			// embed triple-backticks in a code sample; the check must see the
-			// fence as properly closed and not treat the rest of the document
-			// as still-inside-fence.
-			name:     "longer close marker closes fence correctly",
-			mode:     "replace_range",
-			markdown: "```\nsome code\n````\n\nprose paragraph after",
-			wantHint: true, // the blank line AFTER the fence is real prose
-		},
-		{
-			name:     "longer close marker still hides blank line inside fence",
-			mode:     "replace_range",
-			markdown: "```\nbefore\n\nafter\n````",
-			wantHint: false,
-		},
-		{
-			// 4+ leading spaces make the line an indented code block, not a
-			// fence open. The "fence"-looking line is code content; the
-			// surrounding blank must still be detected.
-			name:     "four-space indented fence-like line is not a fence open",
-			mode:     "replace_range",
-			markdown: "first paragraph\n\n    ```\n    code\n    ```",
-			wantHint: true,
-		},
-		{
-			// A tab in the leading whitespace is always ≥4 columns and thus
-			// forces indented-code-block semantics.
-			name:     "tab-indented fence-like line is not a fence open",
-			mode:     "replace_range",
-			markdown: "first paragraph\n\n\t```\n\tcode\n\t```",
-			wantHint: true,
-		},
-		{
-			// 3 leading spaces is still within the fence-tolerance window.
-			name:     "three-space indented fence is still a fence",
-			mode:     "replace_range",
-			markdown: "   ```\ncode\n\nmore\n   ```",
-			wantHint: false,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			got := checkDocsUpdateReplaceMultilineMarkdown(tt.mode, tt.markdown)
-			hasHint := got != ""
-			if hasHint != tt.wantHint {
-				t.Fatalf("checkDocsUpdateReplaceMultilineMarkdown(%q, %q) = %q, wantHint=%v",
-					tt.mode, tt.markdown, got, tt.wantHint)
-			}
-			if tt.wantHint && (!strings.Contains(got, "delete_range") || !strings.Contains(got, "insert_before")) {
-				t.Errorf("hint should suggest delete_range/insert_before remediation, got: %s", got)
-			}
-		})
-	}
-}
-
-func TestCheckDocsUpdateBoldItalic(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		input    string
-		wantHint bool
-	}{
-		{
-			name:     "triple asterisks flagged",
-			input:    "a ***key insight*** here",
-			wantHint: true,
-		},
-		{
-			name:     "triple asterisks single char flagged",
-			input:    "a ***X*** here",
-			wantHint: true,
-		},
-		{
-			name:     "bold wrapping underscore italic flagged",
-			input:    "note: **_important_** detail",
-			wantHint: true,
-		},
-		{
-			name:     "underscore wrapping double asterisk flagged",
-			input:    "note: _**important**_ detail",
-			wantHint: true,
-		},
-		{
-			name:     "plain bold is fine",
-			input:    "this is **bold** text",
-			wantHint: false,
-		},
-		{
-			name:     "plain italic is fine",
-			input:    "this is *italic* or _italic_ text",
-			wantHint: false,
-		},
-		{
-			name:     "horizontal rule is not flagged",
-			input:    "paragraph\n\n---\n\nnext",
-			wantHint: false,
-		},
-		{
-			name:     "bold followed by italic with space is not flagged",
-			input:    "**bold** and *italic*",
-			wantHint: false,
-		},
-		{
-			name:     "empty input is fine",
-			input:    "",
-			wantHint: false,
-		},
-		{
-			// The emphasis check must not fire on literal Markdown samples
-			// inside a fenced code block — the canonical use case is docs
-			// authors pasting tutorials that demonstrate these exact patterns.
-			name:     "triple asterisks inside backtick fenced code is not flagged",
-			input:    "example:\n```\nthe shape ***keyword*** downgrades\n```",
-			wantHint: false,
-		},
-		{
-			name:     "underscore-bold inside fenced code is not flagged",
-			input:    "example:\n```markdown\nuse **_strong italic_** carefully\n```",
-			wantHint: false,
-		},
-		{
-			name:     "bold-underscore inside fenced code is not flagged",
-			input:    "example:\n~~~\n_**outside-underscore**_ is a bad shape\n~~~",
-			wantHint: false,
-		},
-		{
-			name:     "triple asterisks inside inline code span is not flagged",
-			input:    "the literal `***text***` marker is just a sample",
-			wantHint: false,
-		},
-		{
-			name:     "underscore-bold inside inline code is not flagged",
-			input:    "the shape `**_italic_**` would downgrade, but only if it were real",
-			wantHint: false,
-		},
-		{
-			name:     "escaped triple asterisks rendered as literal text is not flagged",
-			input:    `the literal \***text*** with escaped opener`,
-			wantHint: false,
-		},
-		{
-			name:     "escaped bold inside underscore-italic is not flagged",
-			input:    `shape \*\*_text_\*\* is literal, not emphasis`,
-			wantHint: false,
-		},
-		{
-			// Real emphasis outside the code span must still be detected —
-			// the strip step must not over-sanitize.
-			name:     "real triple asterisks outside inline code still flags",
-			input:    "real ***strong*** and literal `***keyword***` — the first one counts",
-			wantHint: true,
-		},
-		{
-			name:     "real triple asterisks outside fenced code still flags",
-			input:    "real ***strong***\n\n```\nliteral ***keyword*** in code\n```",
-			wantHint: true,
-		},
-		// --- Triple-underscore combined emphasis: ___text___ ---
-		{
-			name:     "triple underscores flagged",
-			input:    "a ___key insight___ here",
-			wantHint: true,
-		},
-		{
-			name:     "triple underscores single char flagged",
-			input:    "a ___X___ here",
-			wantHint: true,
-		},
-		{
-			name:     "triple underscores inside fenced code not flagged",
-			input:    "sample:\n```\nuse ___keyword___ carefully\n```",
-			wantHint: false,
-		},
-		{
-			name:     "triple underscores inside inline code not flagged",
-			input:    "the literal `___phrase___` marker",
-			wantHint: false,
-		},
-		{
-			name:     "escaped triple underscores not flagged",
-			input:    `literal \___phrase___ with escaped opener`,
-			wantHint: false,
-		},
-		// --- Underscore-bold wrapping asterisk-italic: __*text*__ ---
-		{
-			name:     "underscore-bold wrapping asterisk-italic flagged",
-			input:    "note: __*important*__ text",
-			wantHint: true,
-		},
-		{
-			name:     "underscore-bold wrapping asterisk-italic inside fenced code not flagged",
-			input:    "```\nnote: __*important*__ sample\n```",
-			wantHint: false,
-		},
-		{
-			name:     "underscore-bold wrapping asterisk-italic inside inline code not flagged",
-			input:    "literal `__*important*__` marker",
-			wantHint: false,
-		},
-		// --- Asterisk-italic wrapping underscore-bold: *__text__* ---
-		{
-			name:     "asterisk-italic wrapping underscore-bold flagged",
-			input:    "note: *__phrase__* text",
-			wantHint: true,
-		},
-		{
-			name:     "asterisk-italic wrapping underscore-bold inside fenced code not flagged",
-			input:    "```md\nnote: *__phrase__* sample\n```",
-			wantHint: false,
-		},
-		// --- Positive tests: real emphasis in prose coexisting with fake in code ---
-		{
-			// Underscore-variant in prose must still fire when an asterisk
-			// variant appears inside a code span — verifies the strip does
-			// not over-sanitize across the six regex alternatives.
-			name:     "real triple underscores outside inline code still flag when asterisk variant is in code",
-			input:    "real ___strong___ and literal `***shape***` in code",
-			wantHint: true,
-		},
-		{
-			// Longer close fence closes properly; real ***emphasis*** after
-			// the fence must fire.
-			name:     "real emphasis after a fence closed by longer marker still flags",
-			input:    "```\nliteral ***phrase*** in code\n````\n\nand then real ***phrase*** after",
-			wantHint: true,
-		},
-		{
-			// 4-space indented "```" is an indented code block, not a fence
-			// open. The fence helper should refuse it; emphasis outside the
-			// (non-existent) fence must still be detected.
-			name:     "four-space indented fence-like line does not open a fence for the emphasis check",
-			input:    "prose\n\n    ```\n    not a fence\n    ```\n\nreal ***strong*** here",
-			wantHint: true,
-		},
-		{
-			// 3-space indented fence is valid per CommonMark. Emphasis inside
-			// must be sanitized away, so the check must not fire.
-			name:     "three-space indented fence still hides triple-asterisk inside",
-			input:    "   ```\n   literal ***text*** inside\n   ```",
-			wantHint: false,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			got := checkDocsUpdateBoldItalic(tt.input)
-			hasHint := got != ""
-			if hasHint != tt.wantHint {
-				t.Fatalf("checkDocsUpdateBoldItalic(%q) = %q, wantHint=%v", tt.input, got, tt.wantHint)
-			}
-		})
-	}
-}
-
-func TestDocsUpdateWarningsAggregates(t *testing.T) {
-	t.Parallel()
-
-	// Both flags trigger: replace_range with blank line AND triple-asterisk.
-	warnings := docsUpdateWarnings("replace_range", "***opening***\n\nsecond paragraph")
-	if len(warnings) != 2 {
-		t.Fatalf("expected 2 warnings, got %d: %v", len(warnings), warnings)
-	}
-}
-
-func TestDocsUpdateWarningsEmpty(t *testing.T) {
-	t.Parallel()
-
-	// Clean markdown in a non-replace mode produces zero warnings.
-	warnings := docsUpdateWarnings("insert_before", "plain paragraph text")
-	if len(warnings) != 0 {
-		t.Fatalf("expected no warnings, got: %v", warnings)
-	}
-}

shortcuts/doc/docs_update_test.go

@@ -3,9 +3,12 @@
 package doc
 
 import (
-	"reflect"
+	"context"
 	"strings"
 	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
 // ── V2 tests ──
@@ -31,199 +34,102 @@ func TestValidCommandsV2(t *testing.T) {
 	}
 }
 
-// ── V1 tests ──
+func TestDocsUpdateDryRunAcceptsDeprecatedAPIVersionValues(t *testing.T) {
+	for _, apiVersion := range []string{"v1", "v2"} {
+		t.Run(apiVersion, func(t *testing.T) {
+			t.Parallel()
 
-func TestSelectionRequiredMessageV1ReplaceAllSuggestsOverwrite(t *testing.T) {
-	t.Parallel()
+			runtime := newUpdateShortcutTestRuntime(t, apiVersion, nil)
+			if err := validateUpdateV2(context.Background(), runtime); err != nil {
+				t.Fatalf("validateUpdateV2() error = %v", err)
+			}
 
-	msg := selectionRequiredMessageV1("replace_all")
-	for _, needle := range []string{
-		"--replace_all mode requires --selection-with-ellipsis or --selection-by-title",
-		"replace the entire document body",
-		"--mode overwrite",
-	} {
-		if !strings.Contains(msg, needle) {
-			t.Fatalf("message missing %q: %s", needle, msg)
-		}
+			dry := decodeDocDryRun(t, DocsUpdate.DryRun(context.Background(), runtime))
+			if len(dry.API) != 1 {
+				t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
+			}
+			if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnUpdateDryRun"; got != want {
+				t.Fatalf("dry-run URL = %q, want %q", got, want)
+			}
+			if got, want := dry.API[0].Body["command"], "block_insert_after"; got != want {
+				t.Fatalf("dry-run command = %#v, want %q", got, want)
+			}
+			if got, want := dry.API[0].Body["block_id"], "-1"; got != want {
+				t.Fatalf("dry-run block_id = %#v, want %q", got, want)
+			}
+		})
 	}
 }
 
-func TestSelectionRequiredMessageV1OtherModesDoNotSuggestOverwrite(t *testing.T) {
-	t.Parallel()
-
-	msg := selectionRequiredMessageV1("replace_range")
-	if strings.Contains(msg, "--mode overwrite") {
-		t.Fatalf("replace_range message should not suggest overwrite: %s", msg)
-	}
-	if !strings.Contains(msg, "--replace_range mode requires --selection-with-ellipsis or --selection-by-title") {
-		t.Fatalf("unexpected message: %s", msg)
-	}
-}
-
-func TestIsWhiteboardCreateMarkdown(t *testing.T) {
-	t.Run("blank whiteboard tags", func(t *testing.T) {
-		markdown := "<whiteboard type=\"blank\"></whiteboard>\n<whiteboard type=\"blank\"></whiteboard>"
-		if !isWhiteboardCreateMarkdown(markdown) {
-			t.Fatalf("expected blank whiteboard markdown to be treated as whiteboard creation")
-		}
-	})
-
-	t.Run("mermaid code block", func(t *testing.T) {
-		markdown := "```mermaid\ngraph TD\nA-->B\n```"
-		if !isWhiteboardCreateMarkdown(markdown) {
-			t.Fatalf("expected mermaid markdown to be treated as whiteboard creation")
-		}
-	})
-
-	t.Run("plain markdown", func(t *testing.T) {
-		markdown := "## plain text"
-		if isWhiteboardCreateMarkdown(markdown) {
-			t.Fatalf("did not expect plain markdown to be treated as whiteboard creation")
-		}
-	})
-}
-
-func TestCheckOverwriteResourceBlocks(t *testing.T) {
-	t.Parallel()
-
+func TestDocsUpdateRejectsLegacyFlags(t *testing.T) {
 	tests := []struct {
 		name     string
-		markdown string
-		wantWarn bool
-		wantSubs []string
+		setFlags map[string]string
+		want     []string
 	}{
 		{
-			name:     "empty markdown is clean",
-			markdown: "",
-			wantWarn: false,
-		},
-		{
-			name:     "plain prose is clean",
-			markdown: "## Heading\n\nsome text",
-			wantWarn: false,
-		},
-		{
-			name:     "single whiteboard triggers warning",
-			markdown: `<whiteboard token="abc123"/>`,
-			wantWarn: true,
-			wantSubs: []string{"1 whiteboard block", "overwrite"},
-		},
-		{
-			name:     "multiple whiteboards counted",
-			markdown: "<whiteboard token=\"a\"/>\n<whiteboard token=\"b\"/>",
-			wantWarn: true,
-			wantSubs: []string{"2 whiteboard blocks"},
-		},
-		{
-			name:     "single file attachment triggers warning",
-			markdown: `<file token="tok" name="report.pdf"/>`,
-			wantWarn: true,
-			wantSubs: []string{"1 file attachment block"},
-		},
-		{
-			name:     "multiple file attachments counted",
-			markdown: "<file token=\"a\"/>\n<file token=\"b\"/>\n<file token=\"c\"/>",
-			wantWarn: true,
-			wantSubs: []string{"3 file attachment blocks"},
-		},
-		{
-			name:     "whiteboard and file together both counted",
-			markdown: "<whiteboard token=\"wb\"/>\n<file token=\"f\"/>",
-			wantWarn: true,
-			wantSubs: []string{"1 whiteboard block", "1 file attachment block"},
+			name:     "legacy mode",
+			setFlags: map[string]string{"mode": "overwrite"},
+			want: []string{
+				"docs +update is v2-only",
+				"the old v1 interface has been shut down",
+				"legacy v1 flag(s) --mode are no longer supported",
+				"--mode -> use --command",
+				"lark-cli skills read lark-doc references/lark-doc-update.md",
+				"lark-cli skills read lark-doc references/lark-doc-xml.md",
+				"lark-cli skills read lark-doc references/lark-doc-md.md",
+				"follow the latest format rules",
+				"MUST NOT grep/open local SKILL.md files",
+				"lark-cli docs +update --help",
+			},
 		},
 	}
+
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			got := checkOverwriteResourceBlocks(tt.markdown)
-			if (got != "") != tt.wantWarn {
-				t.Fatalf("checkOverwriteResourceBlocks(%q) = %q, wantWarn=%v", tt.markdown, got, tt.wantWarn)
+
+			runtime := newUpdateShortcutTestRuntime(t, "", tt.setFlags)
+			err := validateUpdateV2(context.Background(), runtime)
+			if err == nil {
+				t.Fatal("expected v2-only validation error")
 			}
-			for _, sub := range tt.wantSubs {
-				if !strings.Contains(got, sub) {
-					t.Errorf("expected warning to contain %q, got: %s", sub, got)
+			for _, want := range tt.want {
+				if !strings.Contains(err.Error(), want) {
+					t.Fatalf("error missing %q: %v", want, err)
 				}
 			}
 		})
 	}
 }
 
-func TestNormalizeWhiteboardResult(t *testing.T) {
-	t.Run("adds empty board_tokens when whiteboard creation response omits it", func(t *testing.T) {
-		result := map[string]interface{}{
-			"success": true,
+func newUpdateShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[string]string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "+update"}
+	cmd.Flags().String("api-version", "", "")
+	cmd.Flags().String("doc", "doxcnUpdateDryRun", "")
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("command", "append", "")
+	cmd.Flags().Int("revision-id", -1, "")
+	cmd.Flags().String("content", "<p>hello</p>", "")
+	cmd.Flags().String("pattern", "", "")
+	cmd.Flags().String("block-id", "", "")
+	cmd.Flags().String("src-block-ids", "", "")
+	cmd.Flags().String("mode", "", "")
+	cmd.Flags().String("markdown", "", "")
+	cmd.Flags().String("selection-with-ellipsis", "", "")
+	cmd.Flags().String("selection-by-title", "", "")
+	cmd.Flags().String("new-title", "", "")
+	if apiVersion != "" {
+		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
+			t.Fatalf("set api-version: %v", err)
 		}
-
-		normalizeWhiteboardResult(result, "<whiteboard type=\"blank\"></whiteboard>")
-
-		got, ok := result["board_tokens"].([]string)
-		if !ok {
-			t.Fatalf("expected board_tokens to be []string, got %T", result["board_tokens"])
-		}
-		if len(got) != 0 {
-			t.Fatalf("expected empty board_tokens, got %#v", got)
-		}
-	})
-
-	t.Run("normalizes board_tokens to string slice", func(t *testing.T) {
-		result := map[string]interface{}{
-			"board_tokens": []interface{}{"board_1", "board_2"},
-		}
-
-		normalizeWhiteboardResult(result, "<whiteboard type=\"blank\"></whiteboard>")
-
-		want := []string{"board_1", "board_2"}
-		got, ok := result["board_tokens"].([]string)
-		if !ok {
-			t.Fatalf("expected board_tokens to be []string, got %T", result["board_tokens"])
-		}
-		if !reflect.DeepEqual(got, want) {
-			t.Fatalf("board_tokens mismatch: got %#v want %#v", got, want)
-		}
-	})
-
-	t.Run("leaves non whiteboard response unchanged", func(t *testing.T) {
-		result := map[string]interface{}{
-			"success": true,
-		}
-
-		normalizeWhiteboardResult(result, "## plain text")
-
-		if _, ok := result["board_tokens"]; ok {
-			t.Fatalf("did not expect board_tokens for non-whiteboard markdown")
-		}
-	})
-}
-
-func TestValidateSelectionByTitleV1(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name    string
-		title   string
-		wantErr bool
-		errSub  string
-	}{
-		{name: "empty title is valid", title: "", wantErr: false},
-		{name: "single heading is valid", title: "## Section", wantErr: false},
-		{name: "h1 heading is valid", title: "# Top", wantErr: false},
-		{name: "deep heading is valid", title: "### Sub-section", wantErr: false},
-		{name: "missing hash prefix is invalid", title: "No hash", wantErr: true, errSub: "'#'"},
-		{name: "multiline title is invalid", title: "## First\n## Second", wantErr: true, errSub: "single"},
-		{name: "title with embedded carriage return is invalid", title: "## Title\r## Next", wantErr: true, errSub: "single"},
-		{name: "leading-space heading is valid after trim", title: "  ## Section", wantErr: false},
 	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-			err := validateSelectionByTitleV1(tt.title)
-			if (err != nil) != tt.wantErr {
-				t.Fatalf("validateSelectionByTitleV1(%q) error = %v, wantErr = %v", tt.title, err, tt.wantErr)
-			}
-			if tt.wantErr && tt.errSub != "" && !strings.Contains(err.Error(), tt.errSub) {
-				t.Errorf("expected error to contain %q, got: %v", tt.errSub, err)
-			}
-		})
+	for name, value := range setFlags {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set %s: %v", name, err)
+		}
 	}
+	return common.TestNewRuntimeContext(cmd, nil)
 }

shortcuts/doc/docs_update_v2.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -24,13 +25,13 @@ var validCommandsV2 = map[string]bool{
 // v2UpdateFlags returns the flag definitions for the v2 (OpenAPI) update path.
 func v2UpdateFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "command", Desc: "operation: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", Hidden: true, Enum: validCommandsV2Keys()},
-		{Name: "doc-format", Desc: "content format (prefer XML)", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "content", Desc: "new content (XML or Markdown)", Hidden: true, Input: []string{common.File, common.Stdin}},
-		{Name: "pattern", Desc: "regex pattern for str_replace", Hidden: true},
-		{Name: "block-id", Desc: "target block ID for block_* operations", Hidden: true},
-		{Name: "src-block-ids", Desc: "source block IDs (comma-separated) for block_copy_insert_after / block_move_after", Hidden: true},
-		{Name: "revision-id", Desc: "base revision (-1 = latest)", Hidden: true, Type: "int", Default: "-1"},
+		{Name: "command", Desc: "operation; requirements: str_replace(--pattern), block_delete(--block-id), block_insert_after/block_replace(--block-id,--content), block_copy_insert_after/block_move_after(--block-id,--src-block-ids), overwrite/append(--content)", Enum: validCommandsV2Keys()},
+		{Name: "doc-format", Desc: "content format for --content; xml is default for precise rich edits, markdown for user-provided Markdown or plain append/overwrite", Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "content", Desc: "replacement or inserted content; XML by default or Markdown when --doc-format markdown; empty with str_replace deletes match. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
+		{Name: "pattern", Desc: "str_replace match pattern; XML mode is inline text, Markdown mode can match multiline text"},
+		{Name: "block-id", Desc: "target anchor/block id for block operations; -1 means document end where supported"},
+		{Name: "src-block-ids", Desc: "comma-separated source block ids for block_copy_insert_after and block_move_after"},
+		{Name: "revision-id", Desc: "base revision id; -1 means latest", Type: "int", Default: "-1"},
 	}
 }
 
@@ -39,15 +40,18 @@ func validCommandsV2Keys() []string {
 }
 
 func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
+	if err := validateDocsV2Only(runtime, "+update", docsUpdateLegacyFlags()); err != nil {
+		return err
+	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
-		return common.FlagErrorf("invalid --doc: %v", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc: %v", err).WithParam("--doc")
 	}
 	cmd := runtime.Str("command")
 	if cmd == "" {
-		return common.FlagErrorf("--command is required")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command is required").WithParam("--command")
 	}
 	if !validCommandsV2[cmd] {
-		return common.FlagErrorf("invalid --command %q, valid: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", cmd)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --command %q, valid: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", cmd).WithParam("--command")
 	}
 	content := runtime.Str("content")
 	pattern := runtime.Str("pattern")
@@ -57,50 +61,50 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	switch cmd {
 	case "str_replace":
 		if pattern == "" {
-			return common.FlagErrorf("--command str_replace requires --pattern")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command str_replace requires --pattern").WithParam("--pattern")
 		}
 	case "block_delete":
 		if blockID == "" {
-			return common.FlagErrorf("--command block_delete requires --block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_delete requires --block-id").WithParam("--block-id")
 		}
 	case "block_insert_after":
 		if blockID == "" {
-			return common.FlagErrorf("--command block_insert_after requires --block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_insert_after requires --block-id").WithParam("--block-id")
 		}
 		if content == "" {
-			return common.FlagErrorf("--command block_insert_after requires --content")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_insert_after requires --content").WithParam("--content")
 		}
 	case "block_copy_insert_after":
 		if blockID == "" {
-			return common.FlagErrorf("--command block_copy_insert_after requires --block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_copy_insert_after requires --block-id").WithParam("--block-id")
 		}
 		if srcBlockIDs == "" {
-			return common.FlagErrorf("--command block_copy_insert_after requires --src-block-ids")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_copy_insert_after requires --src-block-ids").WithParam("--src-block-ids")
 		}
 	case "block_move_after":
 		if blockID == "" {
-			return common.FlagErrorf("--command block_move_after requires --block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after requires --block-id").WithParam("--block-id")
 		}
 		if srcBlockIDs == "" {
-			return common.FlagErrorf("--command block_move_after requires --src-block-ids")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after requires --src-block-ids").WithParam("--src-block-ids")
 		}
 		if content != "" {
-			return common.FlagErrorf("--command block_move_after does not accept --content; use --src-block-ids")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_move_after does not accept --content; use --src-block-ids").WithParam("--content")
 		}
 	case "block_replace":
 		if blockID == "" {
-			return common.FlagErrorf("--command block_replace requires --block-id")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_replace requires --block-id").WithParam("--block-id")
 		}
 		if content == "" {
-			return common.FlagErrorf("--command block_replace requires --content")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command block_replace requires --content").WithParam("--content")
 		}
 	case "overwrite":
 		if content == "" {
-			return common.FlagErrorf("--command overwrite requires --content")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command overwrite requires --content").WithParam("--content")
 		}
 	case "append":
 		if content == "" {
-			return common.FlagErrorf("--command append requires --content")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command append requires --content").WithParam("--content")
 		}
 	}
 	return nil

shortcuts/doc/helpers.go

@@ -8,7 +8,7 @@ import (
 	"encoding/json"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -24,7 +24,7 @@ type documentRef struct {
 func parseDocumentRef(input string) (documentRef, error) {
 	raw := strings.TrimSpace(input)
 	if raw == "" {
-		return documentRef{}, output.ErrValidation("--doc cannot be empty")
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--doc cannot be empty").WithParam("--doc")
 	}
 
 	if token, ok := extractDocumentToken(raw, "/wiki/"); ok {
@@ -37,10 +37,10 @@ func parseDocumentRef(input string) (documentRef, error) {
 		return documentRef{Kind: "doc", Token: token}, nil
 	}
 	if strings.Contains(raw, "://") {
-		return documentRef{}, output.ErrValidation("unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw)
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx URL/token or a wiki URL that resolves to docx", raw).WithParam("--doc")
 	}
 	if strings.ContainsAny(raw, "/?#") {
-		return documentRef{}, output.ErrValidation("unsupported --doc input %q: use a docx token or a wiki URL", raw)
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --doc input %q: use a docx token or a wiki URL", raw).WithParam("--doc")
 	}
 
 	return documentRef{Kind: "docx", Token: raw}, nil
@@ -64,10 +64,10 @@ func extractDocumentToken(raw, marker string) (string, bool) {
 
 // doDocAPI executes an OpenAPI request against the docs_ai endpoints and returns
 // the parsed "data" field from the standard Lark response envelope {code, msg, data}.
-// Uses the log-id-aware variant so the x-tt-logid header is surfaced in both the
-// success payload and error details — doc v2 callers rely on it for support escalations.
+// CallAPITyped lifts the x-tt-logid response header onto the typed error so log_id
+// surfaces for support escalations even when the body omits it.
 func doDocAPI(runtime *common.RuntimeContext, method, apiPath string, body interface{}) (map[string]interface{}, error) {
-	return runtime.DoAPIJSONWithLogID(method, apiPath, nil, body)
+	return runtime.CallAPITyped(method, apiPath, nil, body)
 }
 
 func docsSceneFromContext(ctx context.Context) string {
@@ -87,7 +87,7 @@ func injectDocsScene(runtime *common.RuntimeContext, body map[string]interface{}
 func buildDriveRouteExtra(docID string) (string, error) {
 	extra, err := json.Marshal(map[string]string{"drive_route_token": docID})
 	if err != nil {
-		return "", output.Errorf(output.ExitInternal, "internal_error", "failed to marshal upload extra data: %v", err)
+		return "", errs.NewInternalError(errs.SubtypeUnknown, "failed to marshal upload extra data: %v", err).WithCause(err)
 	}
 	return string(extra), nil
 }

shortcuts/doc/markdown_fix.go

@@ -1,649 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"fmt"
-	"io"
-	"regexp"
-	"strings"
-	"unicode"
-	"unicode/utf8"
-)
-
-// fixExportedMarkdown applies post-processing to Lark-exported Markdown to
-// improve round-trip fidelity on re-import:
-//
-//  1. fixBoldSpacing: removes trailing whitespace before closing ** / *,
-//     and strips redundant ** from ATX headings. Applied only outside fenced
-//     code blocks, and skips inline code spans.
-//
-//  2. normalizeNestedListIndentation: rewrites space-pair-indented nested list
-//     markers to tab-indented markers. This avoids nested ordered list items
-//     being flattened or interpreted as plain text/code on re-import.
-//
-//  3. fixSetextAmbiguity: inserts a blank line before any "---" that immediately
-//     follows a non-empty line, preventing it from being parsed as a Setext H2.
-//     Applied only outside fenced code blocks.
-//
-//  4. fixBlockquoteHardBreaks: inserts a blank blockquote line (">") between
-//     consecutive blockquote content lines so create-doc preserves line breaks.
-//     Applied only outside fenced code blocks.
-//
-//  5. fixTopLevelSoftbreaks: inserts a blank line between adjacent non-empty
-//     lines at the top level and inside content containers (callout,
-//     quote-container, lark-td). Code fences are left untouched, and
-//     consecutive list items / continuations are not separated.
-//
-//  6. fixCalloutEmoji: replaces named emoji aliases (e.g. emoji="warning") with
-//     actual Unicode emoji characters that create-doc understands. Applied only
-//     outside fenced code blocks.
-func fixExportedMarkdown(md string) string {
-	md = applyOutsideCodeFences(md, fixBoldSpacing)
-	md = applyOutsideCodeFences(md, normalizeNestedListIndentation)
-	md = applyOutsideCodeFences(md, fixSetextAmbiguity)
-	md = applyOutsideCodeFences(md, fixBlockquoteHardBreaks)
-	md = fixTopLevelSoftbreaks(md)
-	md = applyOutsideCodeFences(md, fixCalloutEmoji)
-	// Collapse runs of 3+ consecutive newlines into exactly 2 (one blank line),
-	// but only outside fenced code blocks to preserve intentional blank lines in code.
-	md = applyOutsideCodeFences(md, func(s string) string {
-		for strings.Contains(s, "\n\n\n") {
-			s = strings.ReplaceAll(s, "\n\n\n", "\n\n")
-		}
-		return s
-	})
-	md = strings.TrimRight(md, "\n") + "\n"
-	return md
-}
-
-// applyOutsideCodeFences applies fn only to content outside fenced code blocks.
-// Lines inside fenced code blocks (``` ... ```) are passed through unchanged,
-// preventing transforms from corrupting literal code content.
-func applyOutsideCodeFences(md string, fn func(string) string) string {
-	lines := strings.Split(md, "\n")
-	var out []string
-	var chunk []string
-	inCode := false
-
-	flush := func() {
-		if len(chunk) == 0 {
-			return
-		}
-		out = append(out, strings.Split(fn(strings.Join(chunk, "\n")), "\n")...)
-		chunk = chunk[:0]
-	}
-
-	for _, line := range lines {
-		trimmed := strings.TrimSpace(line)
-		if strings.HasPrefix(trimmed, "```") {
-			if !inCode {
-				flush()
-				inCode = true
-			} else if trimmed == "```" {
-				inCode = false
-			}
-			out = append(out, line)
-			continue
-		}
-		if inCode {
-			out = append(out, line)
-		} else {
-			chunk = append(chunk, line)
-		}
-	}
-	flush()
-	return strings.Join(out, "\n")
-}
-
-// fixBlockquoteHardBreaks inserts a blank blockquote line (">") between
-// consecutive blockquote content lines. This forces each line into its own
-// paragraph within the blockquote, so MCP create-doc preserves line breaks
-// instead of collapsing them into a single paragraph.
-//
-// Before: "> line1\n> line2"  →  After: "> line1\n>\n> line2"
-func fixBlockquoteHardBreaks(md string) string {
-	lines := strings.Split(md, "\n")
-	out := make([]string, 0, len(lines)*2)
-	for i, line := range lines {
-		out = append(out, line)
-		if strings.HasPrefix(line, "> ") && i+1 < len(lines) && strings.HasPrefix(lines[i+1], "> ") {
-			out = append(out, ">")
-		}
-	}
-	return strings.Join(out, "\n")
-}
-
-// fixBoldSpacing normalizes emphasis markers exported by Lark while preserving
-// inline code spans:
-//
-//  1. Removes leading whitespace after opening ** and * delimiters:
-//     "** text**" → "**text**", "* text*" → "*text*"
-//
-//  2. Removes trailing whitespace before closing ** and * delimiters:
-//     "**text **" → "**text**", "*text *" → "*text*"
-//
-//  3. Removes redundant bold around an entire ATX heading:
-//     "# **text**" → "# text"
-//
-// The bold and italic spacing fixes only run on non-code segments so literal
-// code content is left unchanged.
-var (
-	// headingBoldRe uses [^*]+ (no asterisks) to avoid mismatching headings
-	// that contain multiple disjoint bold spans such as "# **foo** and **bar**".
-	headingBoldRe = regexp.MustCompile(`(?m)^(#{1,6})\s+\*\*([^*]+)\*\*\s*$`)
-)
-
-func fixBoldSpacing(md string) string {
-	lines := strings.Split(md, "\n")
-	for i, line := range lines {
-		lines[i] = fixBoldSpacingLine(line)
-	}
-	md = strings.Join(lines, "\n")
-	md = headingBoldRe.ReplaceAllString(md, "$1 $2")
-	return md
-}
-
-// atxHeadingRe matches ATX heading lines (# ... through ###### ...).
-var atxHeadingRe = regexp.MustCompile(`^#{1,6}\s`)
-
-// scanInlineCodeSpans returns the byte ranges [start, end) of all inline code
-// spans in line. It handles multi-backtick delimiters (e.g. “ `foo` “) by
-// finding the opening run of N backticks and searching for the next identical
-// run to close the span, per CommonMark spec §6.1.
-func scanInlineCodeSpans(line string) [][2]int {
-	var spans [][2]int
-	i := 0
-	for i < len(line) {
-		if line[i] != '`' {
-			i++
-			continue
-		}
-		// Count the opening backtick run.
-		start := i
-		for i < len(line) && line[i] == '`' {
-			i++
-		}
-		delim := line[start:i] // e.g. "`" or "``" or "```"
-		// Search for the closing run of the same length.
-		j := i
-		for j <= len(line)-len(delim) {
-			if line[j] == '`' {
-				k := j
-				for k < len(line) && line[k] == '`' {
-					k++
-				}
-				if k-j == len(delim) {
-					spans = append(spans, [2]int{start, k})
-					i = k
-					break
-				}
-				j = k // skip this backtick run and keep searching
-			} else {
-				j++
-			}
-		}
-		// No closing delimiter found — not a code span, continue.
-	}
-	return spans
-}
-
-// fixBoldSpacingLine applies bold/italic trailing-space fixes to a single line,
-// skipping content inside inline code spans to avoid corrupting literal code.
-// ATX heading lines are also skipped here because headingBoldRe in fixBoldSpacing
-// handles them separately, keeping heading-only normalization isolated from the
-// inline emphasis spacing scanner below.
-func fixBoldSpacingLine(line string) string {
-	if atxHeadingRe.MatchString(line) {
-		return line
-	}
-	spans := scanInlineCodeSpans(line)
-	if len(spans) == 0 {
-		return fixEmphasisSpacingSegment(line)
-	}
-	var sb strings.Builder
-	pos := 0
-	for _, loc := range spans {
-		// Process the non-code segment before this inline code span.
-		seg := line[pos:loc[0]]
-		sb.WriteString(fixEmphasisSpacingSegment(seg))
-		// Preserve inline code span as-is.
-		sb.WriteString(line[loc[0]:loc[1]])
-		pos = loc[1]
-	}
-	// Remaining non-code segment after the last code span.
-	sb.WriteString(fixEmphasisSpacingSegment(line[pos:]))
-	return sb.String()
-}
-
-// fixEmphasisSpacingSegment trims only the whitespace immediately inside simple
-// *...* and **...** spans. It deliberately ignores runs of 3+ asterisks and
-// any candidate whose payload contains another asterisk so nested emphasis-like
-// text remains untouched. When both inner sides contain whitespace, single-rune
-// payloads are preserved as literal text (for example "* x *" and "** x **").
-func fixEmphasisSpacingSegment(seg string) string {
-	if !strings.Contains(seg, "*") {
-		return seg
-	}
-
-	var sb strings.Builder
-	pos := 0
-	for pos < len(seg) {
-		openStart, openEnd, ok := nextAsteriskRun(seg, pos)
-		if !ok {
-			sb.WriteString(seg[pos:])
-			break
-		}
-
-		sb.WriteString(seg[pos:openStart])
-
-		markerLen := openEnd - openStart
-		if markerLen != 1 && markerLen != 2 {
-			sb.WriteString(seg[openStart:openEnd])
-			pos = openEnd
-			continue
-		}
-
-		closeStart, closeEnd, ok := nextAsteriskRun(seg, openEnd)
-		if !ok || closeEnd-closeStart != markerLen {
-			sb.WriteString(seg[openStart:openEnd])
-			pos = openEnd
-			continue
-		}
-
-		payload := seg[openEnd:closeStart]
-		normalized, shouldNormalize := normalizeEmphasisPayload(payload)
-		if !shouldNormalize {
-			sb.WriteString(seg[openStart:closeEnd])
-			pos = closeEnd
-			continue
-		}
-
-		marker := seg[openStart:openEnd]
-		sb.WriteString(marker)
-		sb.WriteString(normalized)
-		sb.WriteString(marker)
-		pos = closeEnd
-	}
-	return sb.String()
-}
-
-func nextAsteriskRun(s string, start int) (runStart, runEnd int, ok bool) {
-	for i := start; i < len(s); i++ {
-		if s[i] != '*' {
-			continue
-		}
-		j := i
-		for j < len(s) && s[j] == '*' {
-			j++
-		}
-		return i, j, true
-	}
-	return 0, 0, false
-}
-
-func normalizeEmphasisPayload(payload string) (string, bool) {
-	trimmedLeft := strings.TrimLeftFunc(payload, unicode.IsSpace)
-	trimmed := strings.TrimRightFunc(trimmedLeft, unicode.IsSpace)
-	if trimmed == "" {
-		return payload, false
-	}
-
-	hasLeadingSpace := len(trimmedLeft) != len(payload)
-	hasTrailingSpace := len(trimmed) != len(trimmedLeft)
-	if !hasLeadingSpace && !hasTrailingSpace {
-		return payload, true
-	}
-
-	if hasLeadingSpace && hasTrailingSpace && utf8.RuneCountInString(trimmed) == 1 {
-		return payload, false
-	}
-	return trimmed, true
-}
-
-var setextRe = regexp.MustCompile(`(?m)^([^\n]+)\n(-{3,}\s*$)`)
-
-func fixSetextAmbiguity(md string) string {
-	return setextRe.ReplaceAllString(md, "$1\n\n$2")
-}
-
-// calloutTypeColors maps the semantic type= shorthand to a recommended
-// [background-color, border-color] pair for Feishu callout blocks.
-// Used only for hint messages — the Markdown itself is never rewritten.
-var calloutTypeColors = map[string][2]string{
-	"warning":   {"light-yellow", "yellow"},
-	"caution":   {"light-orange", "orange"},
-	"note":      {"light-blue", "blue"},
-	"info":      {"light-blue", "blue"},
-	"tip":       {"light-green", "green"},
-	"success":   {"light-green", "green"},
-	"check":     {"light-green", "green"},
-	"error":     {"light-red", "red"},
-	"danger":    {"light-red", "red"},
-	"important": {"light-purple", "purple"},
-}
-
-// calloutOpenTagRe matches a <callout …> opening tag.
-var calloutOpenTagRe = regexp.MustCompile(`<callout(\s[^>]*)?>`)
-
-// calloutTypeAttrRe extracts the value of a type= attribute (single or
-// double quoted) from a callout opening tag's attribute string. The
-// (?:^|\s) anchor instead of \b is intentional: \b sits at any
-// word/non-word boundary, and `-` is a non-word character, so
-// `\btype=` would also match the suffix of `data-type=` and yield a
-// bogus type lookup. Anchoring on start-of-string-or-whitespace
-// requires a real attribute separator before the name.
-var calloutTypeAttrRe = regexp.MustCompile(`(?:^|\s)type=(?:"([^"]*)"|'([^']*)')`)
-
-// calloutBackgroundColorAttrRe matches a background-color= attribute
-// name with optional whitespace around the equals sign, so forms like
-// `background-color="..."` and `background-color = "..."` are both
-// accepted. Same (?:^|\s) anchor as calloutTypeAttrRe, for the same
-// reason: `data-background-color="..."` must not look like a present
-// background-color and silently suppress the hint.
-var calloutBackgroundColorAttrRe = regexp.MustCompile(`(?:^|\s)background-color\s*=`)
-
-// WarnCalloutType scans md for callout tags that carry a type= attribute but
-// no background-color= attribute, then writes a hint line to w for each one
-// suggesting the explicit Feishu color attributes to use instead.
-//
-// Callout tags inside fenced code blocks (``` or ~~~) are skipped — they
-// are documentation samples, not real callouts the user wants Feishu to
-// render. Fence detection uses the shared codeFenceOpenMarker /
-// isCodeFenceClose helpers so both backtick and tilde fences are handled
-// (matching CommonMark §4.5).
-//
-// The Markdown is not modified — the caller is responsible for acting on
-// the hints or ignoring them. This keeps the create/update path
-// transparent: user input reaches create-doc exactly as written.
-func WarnCalloutType(md string, w io.Writer) {
-	fenceMarker := ""
-	for _, line := range strings.Split(md, "\n") {
-		if fenceMarker != "" {
-			// Inside a fenced block — skip everything until the matching
-			// closer. Code samples that show literal <callout type=...>
-			// must not produce a phantom hint.
-			if isCodeFenceClose(line, fenceMarker) {
-				fenceMarker = ""
-			}
-			continue
-		}
-		if marker := codeFenceOpenMarker(line); marker != "" {
-			fenceMarker = marker
-			continue
-		}
-		scanCalloutTagsForWarning(line, w)
-	}
-}
-
-// scanCalloutTagsForWarning emits a hint to w for every <callout type="...">
-// tag in s that lacks an explicit background-color= attribute. Pulled out
-// of WarnCalloutType so the line walker only handles fence state and the
-// per-tag scan is its own readable unit.
-//
-// The previous implementation routed the tag iteration through
-// calloutOpenTagRe.ReplaceAllStringFunc with a callback that always
-// returned the original tag and threw the rebuilt string away — using a
-// rewrite primitive purely for its iteration side-effect, plus a second
-// regex execution to recover the capture groups inside the callback.
-// FindAllStringSubmatch hands us both the iteration and the groups in one
-// pass, no allocation thrown away.
-func scanCalloutTagsForWarning(s string, w io.Writer) {
-	for _, m := range calloutOpenTagRe.FindAllStringSubmatch(s, -1) {
-		attrs := m[1]
-		// Skip tags that already carry an explicit background-color.
-		if calloutBackgroundColorAttrRe.MatchString(attrs) {
-			continue
-		}
-		parts := calloutTypeAttrRe.FindStringSubmatch(attrs)
-		if len(parts) < 3 {
-			continue // no type= attribute
-		}
-		// parts[1] is the double-quoted capture, parts[2] is single-quoted.
-		typeName := parts[1]
-		if typeName == "" {
-			typeName = parts[2]
-		}
-		colors, ok := calloutTypeColors[typeName]
-		if !ok {
-			continue // unknown type — no hint to give
-		}
-		fmt.Fprintf(w,
-			"hint: callout type=%q has no background-color; consider: background-color=%q border-color=%q\n",
-			typeName, colors[0], colors[1])
-	}
-}
-
-// calloutEmojiAliases maps named emoji strings that fetch-doc emits to actual
-// Unicode emoji characters that create-doc accepts.
-var calloutEmojiAliases = map[string]string{
-	"warning":      "⚠️",
-	"note":         "📝",
-	"tip":          "💡",
-	"info":         "ℹ️",
-	"check":        "✅",
-	"success":      "✅",
-	"error":        "❌",
-	"danger":       "🚨",
-	"important":    "❗",
-	"caution":      "⚠️",
-	"question":     "❓",
-	"forbidden":    "🚫",
-	"fire":         "🔥",
-	"star":         "⭐",
-	"pin":          "📌",
-	"clock":        "🕐",
-	"gift":         "🎁",
-	"eyes":         "👀",
-	"bulb":         "💡",
-	"memo":         "📝",
-	"link":         "🔗",
-	"key":          "🔑",
-	"lock":         "🔒",
-	"thumbsup":     "👍",
-	"thumbsdown":   "👎",
-	"rocket":       "🚀",
-	"construction": "🚧",
-}
-
-// calloutEmojiRe matches emoji="<name>" in callout opening tags.
-var calloutEmojiRe = regexp.MustCompile(`(<callout[^>]*\bemoji=")([^"]+)(")`)
-
-// fixCalloutEmoji replaces named emoji aliases in callout tags with actual
-// Unicode emoji characters. fetch-doc sometimes emits emoji="warning" instead
-// of emoji="⚠️"; create-doc only accepts Unicode emoji.
-func fixCalloutEmoji(md string) string {
-	return calloutEmojiRe.ReplaceAllStringFunc(md, func(match string) string {
-		parts := calloutEmojiRe.FindStringSubmatch(match)
-		if len(parts) != 4 {
-			return match
-		}
-		name := parts[2]
-		if emoji, ok := calloutEmojiAliases[name]; ok {
-			return parts[1] + emoji + parts[3]
-		}
-		return match
-	})
-}
-
-// isTableStructuralTag returns true for lark-table tags that are structural
-// (table/tr/td open/close) and should not themselves trigger blank-line insertion.
-func isTableStructuralTag(s string) bool {
-	return strings.HasPrefix(s, "<lark-t") ||
-		strings.HasPrefix(s, "</lark-t")
-}
-
-// contentContainers lists block tags whose interior should have blank lines
-// inserted between adjacent content lines (same treatment as lark-td).
-var contentContainers = [][2]string{
-	{"<lark-td>", "</lark-td>"},
-	{"<callout", "</callout>"},
-	{"<quote-container>", "</quote-container>"},
-}
-
-// listItemRe matches unordered and ordered list item markers, including
-// indented (nested) items.
-var listItemRe = regexp.MustCompile(`^[ \t]*([-*+]|\d+[.)]) `)
-
-// nestedListIndentRe matches nested list item markers indented with pairs of
-// spaces. We rewrite those space pairs to tabs because some downstream
-// round-trip paths treat multi-space indented ordered items as flat items or
-// literal text, while tab indentation remains nested and avoids 4-space code
-// block ambiguity.
-var nestedListIndentRe = regexp.MustCompile(`^( {2,})([-*+]|\d+[.)]) `)
-
-func normalizeNestedListIndentation(md string) string {
-	lines := strings.Split(md, "\n")
-	for i, line := range lines {
-		matches := nestedListIndentRe.FindStringSubmatch(line)
-		if len(matches) != 3 {
-			continue
-		}
-		if !hasPreviousNonBlankListItem(lines, i) {
-			continue
-		}
-		indent := matches[1]
-		if len(indent)%2 != 0 {
-			continue
-		}
-		tabs := strings.Repeat("\t", len(indent)/2)
-		lines[i] = tabs + line[len(indent):]
-	}
-	return strings.Join(lines, "\n")
-}
-
-func hasPreviousNonBlankListItem(lines []string, index int) bool {
-	for i := index - 1; i >= 0; i-- {
-		trimmed := strings.TrimSpace(lines[i])
-		if trimmed == "" {
-			return false
-		}
-		return listItemRe.MatchString(lines[i])
-	}
-	return false
-}
-
-// isListItemOrContinuation returns true for lines that are part of a list:
-// either a list item marker line or an indented continuation of a list item.
-// This is used to prevent blank lines being inserted between tight list lines,
-// which would turn a tight list into a loose list and change rendering.
-func isListItemOrContinuation(line string) bool {
-	if listItemRe.MatchString(line) {
-		return true
-	}
-	// Continuation lines are indented by at least 2 spaces or 1 tab.
-	return strings.HasPrefix(line, "  ") || strings.HasPrefix(line, "\t")
-}
-
-// fixTopLevelSoftbreaks ensures that adjacent non-empty content lines are
-// separated by a blank line in the following contexts:
-//  1. Top level (depth == 0): every Lark block becomes its own Markdown paragraph.
-//  2. Inside content containers (<lark-td>, <callout>, <quote-container>):
-//     multi-line content is preserved as separate paragraphs.
-//
-// Structural table tags (<lark-table>, <lark-tr>, <lark-td> and their closing
-// counterparts) never trigger blank-line insertion themselves. Fenced code
-// blocks (``` ... ```) are left completely untouched. Consecutive list items
-// and list continuations are not separated (to preserve tight lists).
-func fixTopLevelSoftbreaks(md string) string {
-	lines := strings.Split(md, "\n")
-	out := make([]string, 0, len(lines)*2)
-
-	inCodeBlock := false
-	// containerDepth > 0 means we are inside a content container.
-	containerDepth := 0
-	// tableDepth tracks <lark-table> nesting (outer structure, not content).
-	tableDepth := 0
-
-	for i, line := range lines {
-		trimmed := strings.TrimSpace(line)
-
-		// --- Track fenced code blocks — skip all processing inside. ---
-		// Any ``` line opens a block; only plain ``` (no language id) closes it.
-		if strings.HasPrefix(trimmed, "```") {
-			if inCodeBlock {
-				if trimmed == "```" {
-					inCodeBlock = false
-				}
-			} else {
-				inCodeBlock = true
-			}
-			out = append(out, line)
-			continue
-		}
-
-		if !inCodeBlock {
-			// --- Track content containers. ---
-			for _, cc := range contentContainers {
-				if strings.HasPrefix(trimmed, cc[0]) {
-					containerDepth++
-				}
-				if strings.Contains(trimmed, cc[1]) {
-					containerDepth--
-					if containerDepth < 0 {
-						containerDepth = 0
-					}
-				}
-			}
-
-			// --- Track table structure (outer, non-content). ---
-			if strings.HasPrefix(trimmed, "<lark-table") {
-				tableDepth++
-			}
-			if strings.Contains(trimmed, "</lark-table>") {
-				tableDepth--
-				if tableDepth < 0 {
-					tableDepth = 0
-				}
-			}
-		}
-
-		// --- Decide whether to insert a blank line before this line. ---
-		if !inCodeBlock && trimmed != "" && i > 0 {
-			// Skip structural table tags — they are not content lines.
-			isStructural := isTableStructuralTag(trimmed)
-
-			// Don't split consecutive blockquote lines ("> ...") — they form
-			// one continuous blockquote in the original document.
-			isBlockquote := strings.HasPrefix(trimmed, "> ") || trimmed == ">"
-
-			// Only closing container tags suppress blank-line insertion.
-			// Opening container tags may still receive a blank line before them
-			// (e.g. two consecutive <callout> blocks need a blank between them).
-			isContainerTag := false
-			for _, cc := range contentContainers {
-				closingTag := "</" + cc[0][1:]
-				if strings.HasPrefix(trimmed, closingTag) {
-					isContainerTag = true
-					break
-				}
-			}
-
-			// Insert blank line when:
-			//   - at top level (tableDepth == 0, containerDepth == 0), OR
-			//   - inside a content container (containerDepth > 0, not in outer table)
-			// AND this line is actual content (not structural/blockquote/container-tag).
-			inContent := tableDepth == 0 || containerDepth > 0
-			if !isStructural && !isBlockquote && !isContainerTag && inContent {
-				// Don't split consecutive list items / continuations — inserting a
-				// blank line between them turns a tight list into a loose list.
-				isListRelated := isListItemOrContinuation(line)
-				prevIsListRelated := len(out) > 0 && isListItemOrContinuation(out[len(out)-1])
-				if !(isListRelated && prevIsListRelated) {
-					prev := ""
-					if len(out) > 0 {
-						prev = strings.TrimSpace(out[len(out)-1])
-					}
-					if prev != "" && !isTableStructuralTag(prev) {
-						out = append(out, "")
-					}
-				}
-			}
-		}
-
-		out = append(out, line)
-	}
-
-	return strings.Join(out, "\n")
-}

shortcuts/doc/markdown_fix_hardening_test.go

@@ -1,287 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-	"testing"
-)
-
-// TestFixExportedMarkdownIdempotent asserts the core promise of the exported
-// markdown pipeline: applying the fixes twice produces the same result as
-// applying them once. Round-trip formatting relies on this invariant, so any
-// transform that keeps rewriting its own output would break fetch → edit →
-// update → fetch stability.
-func TestFixExportedMarkdownIdempotent(t *testing.T) {
-	fixtures := map[string]string{
-		"kitchen sink": strings.Join([]string{
-			"# **Title**",
-			"paragraph one",
-			"paragraph two",
-			"**bold ** and * italic*",
-			"",
-			"> q1",
-			"> q2",
-			"",
-			"1. parent",
-			"  1. child",
-			"    1. grandchild",
-			"",
-			"<callout emoji=\"warning\">",
-			"callout body line 1",
-			"callout body line 2",
-			"</callout>",
-			"",
-			"some text",
-			"---",
-			"",
-			"```go",
-			"// code content with markdown-like shapes must survive as-is",
-			"**foo **",
-			"* hello*",
-			"  1. nested",
-			"> q",
-			"---",
-			"```",
-			"",
-		}, "\n"),
-
-		"cjk content": strings.Join([]string{
-			"# **测试标题**",
-			"段落一",
-			"段落二",
-			"**有用性 ** and * 关键 *",
-			"",
-			"1. 父项",
-			"  1. 子项",
-			"",
-		}, "\n"),
-
-		"nested containers": strings.Join([]string{
-			"<callout emoji=\"info\">",
-			"line a",
-			"line b",
-			"</callout>",
-			"",
-			"<quote-container>",
-			"quoted 1",
-			"quoted 2",
-			"</quote-container>",
-			"",
-		}, "\n"),
-	}
-
-	for name, fixture := range fixtures {
-		t.Run(name, func(t *testing.T) {
-			once := fixExportedMarkdown(fixture)
-			twice := fixExportedMarkdown(once)
-			if once != twice {
-				t.Errorf("fixExportedMarkdown is not idempotent for %q\nfirst pass:\n%s\nsecond pass:\n%s",
-					name, once, twice)
-			}
-		})
-	}
-}
-
-// TestFixExportedMarkdownPreservesFencedCodeByteForByte packs a fenced code
-// block with content that every individual transform in the pipeline would
-// normally rewrite, and asserts the fence content comes out byte-for-byte
-// identical. This is the pipeline's strongest invariant — users' code samples
-// must never be silently modified by a formatting pass.
-func TestFixExportedMarkdownPreservesFencedCodeByteForByte(t *testing.T) {
-	// Every line below is something at least one transform would touch if it
-	// appeared outside a fence. None of it must change.
-	dangerous := strings.Join([]string{
-		"**foo **",      // fixBoldSpacing — trailing space bold
-		"* hello*",      // fixBoldSpacing — leading space italic
-		"# **heading**", // fixBoldSpacing — redundant heading bold
-		"para1",         // fixTopLevelSoftbreaks — adjacent paragraphs
-		"para2",
-		"> q1", // fixBlockquoteHardBreaks — blockquote pair
-		"> q2",
-		"some text", // fixSetextAmbiguity — text before ---
-		"---",
-		"  1. nested",               // normalizeNestedListIndentation
-		`<callout emoji="warning">`, // fixCalloutEmoji — emoji alias
-	}, "\n")
-
-	// Wrap the dangerous content in a triple-backtick fence and surround with
-	// content so the pipeline has adjacent regions to potentially touch.
-	input := "before\n\n```\n" + dangerous + "\n```\n\nafter\n"
-
-	got := fixExportedMarkdown(input)
-
-	// Extract the fence content from the output and compare to the input fence
-	// content byte-for-byte.
-	gotFence, ok := extractFirstFenceContent(got)
-	if !ok {
-		t.Fatalf("fixExportedMarkdown output lost its fenced code block:\n%s", got)
-	}
-	if gotFence != dangerous {
-		t.Errorf("fenced code content was modified\nwant (bytes): %q\ngot  (bytes): %q",
-			dangerous, gotFence)
-	}
-}
-
-// extractFirstFenceContent returns the inner text of the first triple-backtick
-// fenced code block it finds, or ("", false) if none is present.
-func extractFirstFenceContent(md string) (string, bool) {
-	const fence = "```"
-	open := strings.Index(md, fence)
-	if open < 0 {
-		return "", false
-	}
-	// Skip the fence marker and its info-string line.
-	rest := md[open+len(fence):]
-	lineEnd := strings.Index(rest, "\n")
-	if lineEnd < 0 {
-		return "", false
-	}
-	rest = rest[lineEnd+1:]
-	close := strings.Index(rest, "\n"+fence)
-	if close < 0 {
-		return "", false
-	}
-	return rest[:close], true
-}
-
-// TestFixExportedMarkdownPreservesCRLF feeds CRLF-terminated markdown (Windows
-// line endings) through the pipeline and asserts that line endings are
-// preserved AND the emphasis/heading transforms still apply — neither
-// silently-LF-normalized nor passed through unchanged.
-func TestFixExportedMarkdownPreservesCRLF(t *testing.T) {
-	lf := "# **Title**\nparagraph one\nparagraph two\n**bold **\n"
-	crlf := strings.ReplaceAll(lf, "\n", "\r\n")
-
-	got := fixExportedMarkdown(crlf)
-
-	// Transforms must still fire: heading bold stripped, trailing-space bold trimmed.
-	if strings.Contains(got, "**Title**") {
-		t.Errorf("heading bold not stripped on CRLF input:\n%q", got)
-	}
-	if strings.Contains(got, "**bold **") {
-		t.Errorf("trailing-space bold not fixed on CRLF input:\n%q", got)
-	}
-	// CRLF line endings must survive — we don't want to silently normalize a
-	// Windows author's document to LF.
-	if !strings.Contains(got, "\r\n") {
-		t.Errorf("CRLF line endings were normalized away:\n%q", got)
-	}
-}
-
-// TestFixExportedMarkdownTransformInteractions covers shapes where more than
-// one transform fires on the same input. Each transform is individually tested
-// elsewhere; these cases guard against composition regressions.
-func TestFixExportedMarkdownTransformInteractions(t *testing.T) {
-	tests := []struct {
-		name         string
-		input        string
-		wantContains []string // substrings that must be present after fixes
-		wantAbsent   []string // substrings that must be absent after fixes
-	}{
-		{
-			name:  "nested list item with trailing-space bold",
-			input: "1. parent\n  1. **child **\n",
-			wantContains: []string{
-				"\t1.",      // nested indent converted to tab
-				"**child**", // trailing space trimmed
-			},
-			wantAbsent: []string{
-				"  1.",       // original two-space indent gone
-				"**child **", // original trailing space gone
-			},
-		},
-		{
-			name:  "paragraph followed by list",
-			input: "paragraph\n- item a\n- item b\n",
-			wantContains: []string{
-				"paragraph\n\n- item a", // blank line inserted at text-to-list transition
-			},
-			wantAbsent: []string{
-				"\n\n\n", // no triple newline
-			},
-		},
-		{
-			name:  "callout containing list with emphasis",
-			input: "<callout emoji=\"info\">\n- **item **\n- another\n</callout>\n",
-			wantContains: []string{
-				"**item**", // trailing-space bold fixed inside callout
-			},
-			wantAbsent: []string{
-				"**item **",
-			},
-		},
-		{
-			name:  "heading followed by paragraph with bold",
-			input: "# **Title**\nbody **text **\n",
-			wantContains: []string{
-				"# Title",       // heading bold stripped
-				"body **text**", // paragraph bold trimmed, not stripped
-			},
-			wantAbsent: []string{
-				"# **Title**",
-				"body **text **",
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixExportedMarkdown(tt.input)
-			for _, want := range tt.wantContains {
-				if !strings.Contains(got, want) {
-					t.Errorf("want substring %q not found in output:\n%s", want, got)
-				}
-			}
-			for _, unwanted := range tt.wantAbsent {
-				if strings.Contains(got, unwanted) {
-					t.Errorf("unwanted substring %q still present in output:\n%s", unwanted, got)
-				}
-			}
-		})
-	}
-}
-
-// TestNormalizeNestedListIndentationDocumentedSkips locks in the deliberate
-// "do nothing" branches of normalizeNestedListIndentation. Each case below is
-// a shape the function intentionally does not rewrite; if a future change to
-// the heuristic flips one of these, we want the regression to be visible in
-// the test diff rather than silently changing user documents.
-func TestNormalizeNestedListIndentationDocumentedSkips(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		// want is identical to input — we are asserting "no change".
-	}{
-		{
-			name:  "three-space indent (odd) under list item stays unchanged",
-			input: "1. parent\n   1. child",
-		},
-		{
-			name:  "five-space indent (odd) under list item stays unchanged",
-			input: "- parent\n     - deep",
-		},
-		{
-			name:  "two-space indent without a parent list item stays unchanged",
-			input: "plain paragraph\n  - not nested",
-		},
-		{
-			name:  "blank-line-separated loose-list sibling stays unchanged",
-			input: "1. a\n\n  1. b",
-		},
-		{
-			name:  "four-space indented code block under list item stays unchanged",
-			input: "- parent\n\n    1. code sample",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := normalizeNestedListIndentation(tt.input)
-			if got != tt.input {
-				t.Errorf("normalizeNestedListIndentation unexpectedly rewrote documented-skip input\ninput: %q\ngot:   %q", tt.input, got)
-			}
-		})
-	}
-}

shortcuts/doc/markdown_fix_test.go

@@ -1,569 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestFixBoldSpacing(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "leading space after opening bold",
-			input: "** hello**",
-			want:  "**hello**",
-		},
-		{
-			name:  "leading space after opening italic",
-			input: "* hello*",
-			want:  "*hello*",
-		},
-		{
-			name:  "leading and trailing spaces inside bold are collapsed",
-			input: "** hello **",
-			want:  "**hello**",
-		},
-		{
-			name:  "leading and trailing spaces inside italic are collapsed",
-			input: "* hello *",
-			want:  "*hello*",
-		},
-		{
-			name:  "multiple spaced italic spans on one line are each collapsed",
-			input: "* a* * b*",
-			want:  "*a* *b*",
-		},
-		{
-			name:  "ambiguous italic span stays literal",
-			input: "2 * x * y",
-			want:  "2 * x * y",
-		},
-		{
-			name:  "ambiguous bold span stays literal",
-			input: "2 ** x ** y",
-			want:  "2 ** x ** y",
-		},
-		{
-			name:  "single-rune italic with spaces on both sides stays literal",
-			input: "* x *",
-			want:  "* x *",
-		},
-		{
-			name:  "single-rune bold with spaces on both sides stays literal",
-			input: "** x **",
-			want:  "** x **",
-		},
-		{
-			name:  "triple-asterisk near miss stays literal",
-			input: "*** hello**",
-			want:  "*** hello**",
-		},
-		{
-			name:  "trailing space before closing bold",
-			input: "**hello **",
-			want:  "**hello**",
-		},
-		{
-			name:  "trailing space before closing italic",
-			input: "*hello *",
-			want:  "*hello*",
-		},
-		{
-			name:  "redundant bold in h1",
-			input: "# **Title**",
-			want:  "# Title",
-		},
-		{
-			name:  "redundant bold in h2",
-			input: "## **Section**",
-			want:  "## Section",
-		},
-		{
-			name:  "no change needed for clean bold",
-			input: "**bold**",
-			want:  "**bold**",
-		},
-		{
-			name:  "multiple lines processed independently",
-			input: "**foo **\n**bar **",
-			want:  "**foo**\n**bar**",
-		},
-		{
-			name:  "inline code span not modified",
-			input: "`**hello **`",
-			want:  "`**hello **`",
-		},
-		{
-			name:  "inline code preserved, bold outside fixed",
-			input: "**foo ** and `**bar **`",
-			want:  "**foo** and `**bar **`",
-		},
-		{
-			name:  "inline code with spaced italic stays literal while outside span is fixed",
-			input: "`* hello *` and * hello *",
-			want:  "`* hello *` and *hello*",
-		},
-		{
-			name:  "opening space inside text tag fixed",
-			input: `<text color="red">** Helpful - 有用性：**</text>`,
-			want:  `<text color="red">**Helpful - 有用性：**</text>`,
-		},
-		{
-			name:  "double-backtick inline code not modified",
-			input: "``**hello **`` and **world **",
-			want:  "``**hello **`` and **world**",
-		},
-		{
-			name:  "double-backtick span containing literal backtick not modified",
-			input: "`` a`b `` and **bold **",
-			want:  "`` a`b `` and **bold**",
-		},
-		{
-			name:  "heading with multiple bold spans left unchanged",
-			input: "# **foo** and **bar**",
-			want:  "# **foo** and **bar**",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixBoldSpacing(tt.input)
-			if got != tt.want {
-				t.Errorf("fixBoldSpacing(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestFixSetextAmbiguity(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "paragraph followed by ---",
-			input: "some text\n---",
-			want:  "some text\n\n---",
-		},
-		{
-			name:  "blank line before --- already",
-			input: "some text\n\n---",
-			want:  "some text\n\n---",
-		},
-		{
-			name:  "heading not affected",
-			input: "# Heading\n---",
-			want:  "# Heading\n\n---",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixSetextAmbiguity(tt.input)
-			if got != tt.want {
-				t.Errorf("fixSetextAmbiguity(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestFixBlockquoteHardBreaks(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "two consecutive blockquote lines",
-			input: "> line1\n> line2",
-			want:  "> line1\n>\n> line2",
-		},
-		{
-			name:  "three consecutive blockquote lines",
-			input: "> a\n> b\n> c",
-			want:  "> a\n>\n> b\n>\n> c",
-		},
-		{
-			name:  "single blockquote line unchanged",
-			input: "> only one",
-			want:  "> only one",
-		},
-		{
-			name:  "non-blockquote not affected",
-			input: "line1\nline2",
-			want:  "line1\nline2",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixBlockquoteHardBreaks(tt.input)
-			if got != tt.want {
-				t.Errorf("fixBlockquoteHardBreaks(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestFixTopLevelSoftbreaks(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "adjacent top-level lines get blank line",
-			input: "paragraph one\nparagraph two",
-			want:  "paragraph one\n\nparagraph two",
-		},
-		{
-			name:  "lines inside code block not modified",
-			input: "```\nline1\nline2\n```",
-			want:  "```\nline1\nline2\n```",
-		},
-		{
-			// callout is a content container: blank lines are inserted between inner lines.
-			name:  "lines inside callout get blank line between them",
-			input: "<callout>\nline1\nline2\n</callout>",
-			want:  "<callout>\n\nline1\n\nline2\n</callout>",
-		},
-		{
-			name:  "lark-td cell content gets blank line",
-			input: "<lark-td>\nline1\nline2\n</lark-td>",
-			want:  "<lark-td>\nline1\n\nline2\n</lark-td>",
-		},
-		{
-			name:  "structural lark-table tags not separated",
-			input: "<lark-table>\n<lark-tr>\n<lark-td>\ncontent\n</lark-td>\n</lark-tr>\n</lark-table>",
-			want:  "<lark-table>\n<lark-tr>\n<lark-td>\ncontent\n</lark-td>\n</lark-tr>\n</lark-table>",
-		},
-		{
-			name:  "blockquote lines not split",
-			input: "> line1\n> line2",
-			want:  "> line1\n> line2",
-		},
-		{
-			name:  "consecutive unordered list items not split",
-			input: "- item a\n- item b\n- item c",
-			want:  "- item a\n- item b\n- item c",
-		},
-		{
-			name:  "consecutive ordered list items not split",
-			input: "1. first\n2. second\n3. third",
-			want:  "1. first\n2. second\n3. third",
-		},
-		{
-			name:  "list continuation not split from item",
-			input: "- item a\n  continuation",
-			want:  "- item a\n  continuation",
-		},
-		{
-			name:  "text to list transition gets blank line",
-			input: "paragraph\n- list item",
-			want:  "paragraph\n\n- list item",
-		},
-		{
-			name:  "adjacent callout blocks get blank line between them",
-			input: "<callout>\ncontent1\n</callout>\n<callout>\ncontent2\n</callout>",
-			want:  "<callout>\n\ncontent1\n</callout>\n\n<callout>\n\ncontent2\n</callout>",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixTopLevelSoftbreaks(tt.input)
-			if got != tt.want {
-				t.Errorf("fixTopLevelSoftbreaks(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestNormalizeNestedListIndentation(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "nested ordered list uses tabs instead of space pairs",
-			input: "1. parent\n  1. child\n    1. grandchild",
-			want:  "1. parent\n\t1. child\n\t\t1. grandchild",
-		},
-		{
-			name:  "nested mixed list markers use tabs instead of space pairs",
-			input: "- parent\n  - child\n    1. grandchild",
-			want:  "- parent\n\t- child\n\t\t1. grandchild",
-		},
-		{
-			name:  "top-level list unchanged",
-			input: "1. parent\n2. sibling",
-			want:  "1. parent\n2. sibling",
-		},
-		{
-			name:  "indented top-level marker without parent list stays unchanged",
-			input: "paragraph\n\n  1. item",
-			want:  "paragraph\n\n  1. item",
-		},
-		{
-			name:  "blank-line-separated loose-list sibling stays unchanged",
-			input: "1. a\n\n  1. b",
-			want:  "1. a\n\n  1. b",
-		},
-		{
-			name:  "indented code block inside list item stays unchanged",
-			input: "- parent\n\n    1. code",
-			want:  "- parent\n\n    1. code",
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := normalizeNestedListIndentation(tt.input)
-			if got != tt.want {
-				t.Errorf("normalizeNestedListIndentation(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestFixExportedMarkdown(t *testing.T) {
-	// End-to-end: all fixes applied together
-	input := "# **Title**\nparagraph one\nparagraph two\n**bold **\n> q1\n> q2\nsome text\n---"
-	result := fixExportedMarkdown(input)
-
-	if strings.Contains(result, "# **Title**") {
-		t.Error("expected heading bold to be stripped")
-	}
-	if !strings.Contains(result, "paragraph one\n\nparagraph two") {
-		t.Error("expected blank line between top-level paragraphs")
-	}
-	if strings.Contains(result, "**bold **") {
-		t.Error("expected trailing space in bold to be fixed")
-	}
-	if !strings.Contains(result, ">\n> q2") {
-		t.Error("expected blockquote hard break inserted")
-	}
-	if strings.Contains(result, "some text\n---") {
-		t.Error("expected blank line before --- to prevent setext heading")
-	}
-	// Should end with exactly one newline
-	if !strings.HasSuffix(result, "\n") || strings.HasSuffix(result, "\n\n") {
-		t.Errorf("expected result to end with exactly one newline, got %q", result[len(result)-5:])
-	}
-	// No triple newlines
-	if strings.Contains(result, "\n\n\n") {
-		t.Error("expected no triple newlines in output")
-	}
-}
-
-func TestWarnCalloutType(t *testing.T) {
-	tests := []struct {
-		name         string
-		input        string
-		wantHint     bool   // whether a hint line is expected
-		hintContains string // substring the hint must contain
-	}{
-		{
-			name:         "warning type without background-color emits hint",
-			input:        `<callout type="warning" emoji="📝">`,
-			wantHint:     true,
-			hintContains: `background-color="light-yellow"`,
-		},
-		{
-			name:         "info type without background-color emits hint",
-			input:        `<callout type="info" emoji="ℹ️">`,
-			wantHint:     true,
-			hintContains: `background-color="light-blue"`,
-		},
-		{
-			name:         "single-quoted type attribute emits hint",
-			input:        `<callout type='warning' emoji="📝">`,
-			wantHint:     true,
-			hintContains: `background-color="light-yellow"`,
-		},
-		{
-			name:     "explicit background-color suppresses hint",
-			input:    `<callout type="warning" emoji="📝" background-color="light-red">`,
-			wantHint: false,
-		},
-		{
-			name:     "whitespace around equals is tolerated in background-color",
-			input:    `<callout type="warning" emoji="📝" background-color = "light-red">`,
-			wantHint: false,
-		},
-		{
-			name:     "unknown type emits no hint",
-			input:    `<callout type="custom" emoji="🔥">`,
-			wantHint: false,
-		},
-		{
-			name:     "no type attribute emits no hint",
-			input:    `<callout emoji="💡" background-color="light-green">`,
-			wantHint: false,
-		},
-		{
-			name:     "non-callout tag emits no hint",
-			input:    `<div type="warning">`,
-			wantHint: false,
-		},
-		{
-			name:         "hint includes border-color suggestion",
-			input:        `<callout type="error" emoji="❌">`,
-			wantHint:     true,
-			hintContains: `border-color="red"`,
-		},
-		{
-			// Regression: the old `\btype=` regex matched the suffix of
-			// `data-type=` because `-` is a non-word character, so a tag
-			// carrying only data-attrs would silently get a bogus hint.
-			// The (?:^|\s) anchor requires a real attribute separator.
-			name:     "data-type attribute does not trigger hint",
-			input:    `<callout data-type="warning" emoji="📝">`,
-			wantHint: false,
-		},
-		{
-			// Symmetric guard for the background-color regex: a future
-			// `data-background-color=` attribute must not be mistaken
-			// for a present background-color and silently suppress the
-			// hint that the real type= would otherwise produce.
-			name:         "data-background-color does not suppress hint",
-			input:        `<callout type="warning" data-background-color="anything">`,
-			wantHint:     true,
-			hintContains: `background-color="light-yellow"`,
-		},
-		{
-			// Regression for the code-fence skip: a documentation sample
-			// inside a ``` fence is NOT a real callout the user wants
-			// rendered, so it must produce no stderr noise.
-			name: "callout inside backtick fence emits no hint",
-			input: "```markdown\n" +
-				`<callout type="warning" emoji="📝">` + "\n" +
-				"```\n",
-			wantHint: false,
-		},
-		{
-			// Same skip works for tilde fences (CommonMark §4.5 makes
-			// `~~~` an equivalent fence character).
-			name: "callout inside tilde fence emits no hint",
-			input: "~~~markdown\n" +
-				`<callout type="info" emoji="ℹ️">` + "\n" +
-				"~~~\n",
-			wantHint: false,
-		},
-		{
-			// Closing the fence must restore normal scanning: a real
-			// callout that follows a documentation block still gets a
-			// hint. Pins that fenceMarker is reset, not stuck.
-			name: "callout after fence close still emits hint",
-			input: "```markdown\n" +
-				`<callout type="warning">sample</callout>` + "\n" +
-				"```\n" +
-				`<callout type="error" emoji="❌">real</callout>` + "\n",
-			wantHint:     true,
-			hintContains: `border-color="red"`,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			var buf strings.Builder
-			WarnCalloutType(tt.input, &buf)
-			got := buf.String()
-			if tt.wantHint {
-				if got == "" {
-					t.Errorf("WarnCalloutType(%q): expected hint, got no output", tt.input)
-					return
-				}
-				if tt.hintContains != "" && !strings.Contains(got, tt.hintContains) {
-					t.Errorf("WarnCalloutType(%q): hint %q missing %q", tt.input, got, tt.hintContains)
-				}
-			} else {
-				if got != "" {
-					t.Errorf("WarnCalloutType(%q): expected no output, got %q", tt.input, got)
-				}
-			}
-		})
-	}
-}
-
-func TestFixCalloutEmoji(t *testing.T) {
-	tests := []struct {
-		name  string
-		input string
-		want  string
-	}{
-		{
-			name:  "warning alias replaced",
-			input: `<callout emoji="warning" background-color="light-orange">`,
-			want:  `<callout emoji="⚠️" background-color="light-orange">`,
-		},
-		{
-			name:  "tip alias replaced",
-			input: `<callout emoji="tip">`,
-			want:  `<callout emoji="💡">`,
-		},
-		{
-			name:  "actual emoji unchanged",
-			input: `<callout emoji="⚠️">`,
-			want:  `<callout emoji="⚠️">`,
-		},
-		{
-			name:  "unknown alias unchanged",
-			input: `<callout emoji="unicorn">`,
-			want:  `<callout emoji="unicorn">`,
-		},
-		{
-			name:  "non-callout tag unchanged",
-			input: `<div emoji="warning">`,
-			want:  `<div emoji="warning">`,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := fixCalloutEmoji(tt.input)
-			if got != tt.want {
-				t.Errorf("fixCalloutEmoji(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestApplyOutsideCodeFences(t *testing.T) {
-	// Transforms should not modify content inside fenced code blocks.
-	input := "```md\n**x **\n> a\n> b\nline\n---\n```"
-
-	if got := applyOutsideCodeFences(input, fixBoldSpacing); got != input {
-		t.Fatalf("fixBoldSpacing (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
-	}
-	if got := applyOutsideCodeFences(input, fixSetextAmbiguity); got != input {
-		t.Fatalf("fixSetextAmbiguity (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
-	}
-	if got := applyOutsideCodeFences(input, fixBlockquoteHardBreaks); got != input {
-		t.Fatalf("fixBlockquoteHardBreaks (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
-	}
-
-	// Content outside the fence should still be transformed.
-	mixed := "**foo ** before\n```\n**x **\n```\n**bar ** after"
-	got := applyOutsideCodeFences(mixed, fixBoldSpacing)
-	if strings.Contains(got, "**foo **") {
-		t.Errorf("fixBoldSpacing did not fix bold before fence: %q", got)
-	}
-	if strings.Contains(got, "**bar **") {
-		t.Errorf("fixBoldSpacing did not fix bold after fence: %q", got)
-	}
-	if !strings.Contains(got, "```\n**x **\n```") {
-		t.Errorf("fixBoldSpacing modified content inside fence: %q", got)
-	}
-}
-
-func TestFixTopLevelSoftbreaksQuoteContainer(t *testing.T) {
-	input := "<quote-container>\nline1\nline2\n</quote-container>"
-	got := fixTopLevelSoftbreaks(input)
-	// quote-container is a content container: blank lines inserted between inner lines.
-	want := "<quote-container>\n\nline1\n\nline2\n</quote-container>"
-	if got != want {
-		t.Errorf("fixTopLevelSoftbreaks quote-container = %q, want %q", got, want)
-	}
-}

shortcuts/doc/shortcuts.go

@@ -9,28 +9,44 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 const docsServiceHelpDefault = `Document and content operations.`
 
-const docsServiceHelpV2 = `Document and content operations (v2).`
+const docsSkillReadCommand = "lark-cli skills read lark-doc"
+const docsXMLSkillReadCommand = "lark-cli skills read lark-doc references/lark-doc-xml.md"
+const docsMDSkillReadCommand = "lark-cli skills read lark-doc references/lark-doc-md.md"
+const docsContentSkillHelp = "AI agents MUST read " +
+	docsXMLSkillReadCommand + " before writing any --content payload; " +
+	"when using --doc-format markdown, also read " + docsMDSkillReadCommand + ". " +
+	"Follow the latest rules there, and MUST NOT grep/open local SKILL.md files " +
+	"to discover this guidance"
 
-var docsVersionSelectionTips = []string{
-	"Docs v1 is deprecated and will be removed soon. Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
-	"After confirming lark-doc is v2, follow that skill's examples and use `--api-version v2` with docs +create, docs +fetch, and docs +update.",
-}
-
-var docsV2VersionSelectionTips = []string{
-	"Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
-}
-
-func docsTipsForVersion(apiVersion string) []string {
-	if apiVersion == "v2" {
-		return docsV2VersionSelectionTips
+func docsSkillReadCommandForShortcut(shortcut string) string {
+	switch strings.TrimPrefix(shortcut, "+") {
+	case "create":
+		return docsSkillReadCommand + " references/lark-doc-create.md"
+	case "fetch":
+		return docsSkillReadCommand + " references/lark-doc-fetch.md"
+	case "update":
+		return docsSkillReadCommand + " references/lark-doc-update.md"
+	default:
+		return docsSkillReadCommand
+	}
+}
+
+func docsHelpCommandForShortcut(shortcut string) string {
+	switch strings.TrimPrefix(shortcut, "+") {
+	case "create":
+		return "lark-cli docs +create --help"
+	case "fetch":
+		return "lark-cli docs +fetch --help"
+	case "update":
+		return "lark-cli docs +update --help"
+	default:
+		return "lark-cli docs --help"
 	}
-	return docsVersionSelectionTips
 }
 
 // Shortcuts returns all docs shortcuts.
@@ -48,45 +64,32 @@ func Shortcuts() []common.Shortcut {
 }
 
 // ConfigureServiceHelp adds docs-specific guidance to the parent `docs` command.
-// The shortcut-level help remains compatible with legacy v1 skills; this parent
-// help switches docs guidance to match the selected API version.
 func ConfigureServiceHelp(cmd *cobra.Command) {
 	if cmd == nil {
 		return
 	}
-	serviceCmd := cmd
-	cmd.Long = strings.TrimSpace(docsServiceHelpDefault)
-	if cmd.Flags().Lookup("api-version") == nil {
-		cmd.Flags().String("api-version", "", "show docs help for API version (v1|v2)")
-		cmdutil.RegisterFlagCompletion(cmd, "api-version", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
-			return []string{"v1", "v2"}, cobra.ShellCompDirectiveNoFileComp
-		})
-	}
-
-	defaultHelp := cmd.HelpFunc()
-	cmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
-		if cmd != serviceCmd {
-			defaultHelp(cmd, args)
-			return
-		}
-
-		apiVersion, _ := cmd.Flags().GetString("api-version")
-		previousLong := cmd.Long
-		if apiVersion == "v2" {
-			cmd.Long = strings.TrimSpace(docsServiceHelpV2)
-		} else {
-			cmd.Long = strings.TrimSpace(docsServiceHelpDefault)
-		}
-		defer func() {
-			cmd.Long = previousLong
-		}()
-
-		defaultHelp(cmd, args)
-		out := cmd.OutOrStdout()
-		fmt.Fprintln(out)
-		fmt.Fprintln(out, "Tips:")
-		for _, tip := range docsTipsForVersion(apiVersion) {
-			fmt.Fprintf(out, "    • %s\n", tip)
-		}
-	})
+	cmd.Long = docsHelpLong(docsServiceHelpDefault, docsSkillReadCommand)
+}
+
+func installDocsShortcutHelp(command string) func(*cobra.Command) {
+	return func(cmd *cobra.Command) {
+		cmd.Long = docsHelpLong(cmd.Short, docsSkillReadCommandForShortcut(command))
+	}
+}
+
+func docsHelpLong(summary, skillReadCommand string) string {
+	return strings.TrimSpace(fmt.Sprintf(`%s
+
+Start here (required for AI agents):
+  %s
+
+  AI agents MUST read the matching embedded skill before choosing flags
+  or running docs commands. Do not skip this step, and do not infer
+  workflows from --help alone. MUST NOT grep/open local SKILL.md files
+  to discover this guidance; use %s so content stays version-matched
+  with this CLI. Skills ship with the CLI and include docs workflows,
+  selector/block-id usage, XML/Markdown formats, and copy-paste examples.
+
+  skills read lark-doc                Docs workflow guide
+  skills read lark-doc <path>         Read a referenced docs skill file`, strings.TrimSpace(summary), skillReadCommand, skillReadCommand))
 }

shortcuts/doc/v2_only.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type docsLegacyFlag struct {
+	Name        string
+	Replacement string
+}
+
+func docsAPIVersionCompatFlag() common.Flag {
+	return common.Flag{
+		Name:    "api-version",
+		Desc:    "deprecated compatibility flag; docs shortcuts always use v2, and both v1/v2 are accepted for rollback-safe skill examples",
+		Default: "v2",
+	}
+}
+
+func docsCreateLegacyFlags() []docsLegacyFlag {
+	return []docsLegacyFlag{
+		{Name: "title", Replacement: "put the title in --content, for example <title>Title</title>"},
+		{Name: "markdown", Replacement: "use --content with --doc-format markdown"},
+		{Name: "folder-token", Replacement: "use --parent-token"},
+		{Name: "wiki-node", Replacement: "use --parent-token"},
+		{Name: "wiki-space", Replacement: "use --parent-position my_library or a concrete parent position"},
+	}
+}
+
+func docsFetchLegacyFlags() []docsLegacyFlag {
+	return []docsLegacyFlag{
+		{Name: "offset", Replacement: "use --scope outline/range/keyword/section for partial reads"},
+		{Name: "limit", Replacement: "use --scope outline/range/keyword/section for partial reads"},
+	}
+}
+
+func docsUpdateLegacyFlags() []docsLegacyFlag {
+	return []docsLegacyFlag{
+		{Name: "mode", Replacement: "use --command"},
+		{Name: "markdown", Replacement: "use --content with --doc-format markdown"},
+		{Name: "selection-with-ellipsis", Replacement: "use --command str_replace with --pattern"},
+		{Name: "selection-by-title", Replacement: "fetch block ids first, then use --command block_replace/block_insert_after with --block-id"},
+		{Name: "new-title", Replacement: "update the title through XML content in --content"},
+	}
+}
+
+func docsLegacyFlagDefinitions(flags []docsLegacyFlag) []common.Flag {
+	out := make([]common.Flag, 0, len(flags))
+	for _, flag := range flags {
+		out = append(out, common.Flag{
+			Name:   flag.Name,
+			Desc:   "deprecated v1 compatibility flag; run `lark-cli skills read lark-doc` for the v2 CLI skill",
+			Hidden: true,
+		})
+	}
+	return out
+}
+
+func validateDocsV2Only(runtime *common.RuntimeContext, shortcut string, legacyFlags []docsLegacyFlag) error {
+	switch apiVersion := strings.TrimSpace(runtime.Str("api-version")); apiVersion {
+	case "", "v1", "v2":
+	default:
+		return docsV2OnlyError(shortcut, "--api-version is deprecated and only accepts v1 or v2; both values execute the v2 API", "--api-version")
+	}
+
+	var used []string
+	var replacements []string
+	for _, flag := range legacyFlags {
+		if !runtime.Changed(flag.Name) {
+			continue
+		}
+		used = append(used, "--"+flag.Name)
+		if flag.Replacement != "" {
+			replacements = append(replacements, "--"+flag.Name+" -> "+flag.Replacement)
+		}
+	}
+	if len(used) == 0 {
+		return nil
+	}
+
+	detail := "the old v1 interface has been shut down; legacy v1 flag(s) " + strings.Join(used, ", ") + " are no longer supported"
+	if len(replacements) > 0 {
+		detail += "; " + strings.Join(replacements, "; ")
+	}
+	return docsV2OnlyError(shortcut, detail, used[0])
+}
+
+func docsV2OnlyError(shortcut, detail, param string) error {
+	err := errs.NewValidationError(
+		errs.SubtypeInvalidArgument,
+		"docs %s is v2-only; %s. Run `%s` for the current schema and examples. AI agents MUST read `%s` (XML) or `%s` (Markdown) and follow the latest format rules there. MUST NOT grep/open local SKILL.md files to discover this guidance; use `lark-cli skills read ...` so content stays version-matched with this CLI. Run `%s` for the latest command flags",
+		shortcut,
+		detail,
+		docsSkillReadCommandForShortcut(shortcut),
+		docsXMLSkillReadCommand,
+		docsMDSkillReadCommand,
+		docsHelpCommandForShortcut(shortcut),
+	)
+	if param != "" {
+		err = err.WithParam(param)
+	}
+	return err
+}

shortcuts/doc/v2_only_test.go

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing.T) {
+	for _, apiVersion := range []string{"", "v1", "v2"} {
+		t.Run(apiVersion, func(t *testing.T) {
+			runtime := docsV2OnlyTestRuntime(t, apiVersion, false)
+			if err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}}); err != nil {
+				t.Fatalf("validateDocsV2Only(%q) error = %v, want nil", apiVersion, err)
+			}
+		})
+	}
+}
+
+func TestValidateDocsV2OnlyRejectsUnknownAPIVersion(t *testing.T) {
+	runtime := docsV2OnlyTestRuntime(t, "v0", false)
+	err := validateDocsV2Only(runtime, "+fetch", nil)
+	if err == nil {
+		t.Fatal("expected unknown --api-version to be rejected")
+	}
+	for _, want := range []string{
+		"docs +fetch is v2-only",
+		"--api-version is deprecated and only accepts v1 or v2",
+		"both values execute the v2 API",
+		"lark-cli skills read lark-doc references/lark-doc-fetch.md",
+		"lark-cli skills read lark-doc references/lark-doc-xml.md",
+		"lark-cli skills read lark-doc references/lark-doc-md.md",
+		"MUST NOT grep/open local SKILL.md files",
+		"lark-cli docs +fetch --help",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error missing %q: %v", want, err)
+		}
+	}
+}
+
+func TestValidateDocsV2OnlyRejectsChangedLegacyFlags(t *testing.T) {
+	runtime := docsV2OnlyTestRuntime(t, "", true)
+	err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}})
+	if err == nil {
+		t.Fatal("expected changed legacy flag to be rejected")
+	}
+	for _, want := range []string{
+		"the old v1 interface has been shut down",
+		"legacy v1 flag(s) --mode are no longer supported",
+		"--mode -> use --command",
+		"lark-cli skills read lark-doc references/lark-doc-update.md",
+		"lark-cli skills read lark-doc references/lark-doc-xml.md",
+		"lark-cli skills read lark-doc references/lark-doc-md.md",
+		"MUST NOT grep/open local SKILL.md files",
+		"lark-cli docs +update --help",
+	} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error missing %q: %v", want, err)
+		}
+	}
+}
+
+func docsV2OnlyTestRuntime(t *testing.T, apiVersion string, legacyMode bool) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "+update"}
+	cmd.Flags().String("api-version", "", "")
+	cmd.Flags().String("mode", "", "")
+	if apiVersion != "" {
+		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
+			t.Fatalf("set api-version: %v", err)
+		}
+	}
+	if legacyMode {
+		if err := cmd.Flags().Set("mode", "overwrite"); err != nil {
+			t.Fatalf("set mode: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, nil)
+}

shortcuts/doc/versioned_help.go

@@ -1,44 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// installVersionedHelp sets a custom help function on cmd that shows only the
-// flags relevant to the selected --api-version. flagVersions maps flag name to
-// its version ("v1" or "v2"). Flags not in the map are treated as shared and
-// always visible.
-func installVersionedHelp(cmd *cobra.Command, defaultVersion string, flagVersions map[string]string) {
-	origHelp := cmd.HelpFunc()
-	cmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
-		ver, _ := cmd.Flags().GetString("api-version")
-		if ver == "" {
-			ver = defaultVersion
-		}
-		// Show/hide flags based on the active version.
-		cmd.Flags().VisitAll(func(f *pflag.Flag) {
-			if fv, ok := flagVersions[f.Name]; ok {
-				f.Hidden = fv != ver
-			}
-		})
-		cmdutil.SetTips(cmd, docsTipsForVersion(ver))
-		origHelp(cmd, args)
-	})
-}
-
-// warnDeprecatedV1 prints a deprecation notice to stderr when the v1 (MCP) code
-// path is used.
-func warnDeprecatedV1(runtime *common.RuntimeContext, shortcut string) {
-	fmt.Fprintf(runtime.IO().ErrOut,
-		"[deprecated] docs %s is using the v1 API. %s\n",
-		shortcut, docsV2VersionSelectionTips[0])
-}

shortcuts/doc/versioned_help_test.go

@@ -1,36 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-func TestWarnDeprecatedV1SuggestsSkillUpdate(t *testing.T) {
-	for _, shortcut := range []string{"+create", "+fetch", "+update"} {
-		t.Run(shortcut, func(t *testing.T) {
-			f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{})
-			warnDeprecatedV1(&common.RuntimeContext{Factory: f}, shortcut)
-
-			got := stderr.String()
-			for _, want := range []string{
-				"[deprecated] docs " + shortcut + " is using the v1 API.",
-				"Check the installed lark-doc skill first",
-				"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
-			} {
-				if !strings.Contains(got, want) {
-					t.Fatalf("warning missing %q:\n%s", want, got)
-				}
-			}
-			if strings.Contains(got, "will be removed in a future release") {
-				t.Fatalf("warning should not include removal-only guidance:\n%s", got)
-			}
-		})
-	}
-}

shortcuts/drive/drive_inspect.go

@@ -8,11 +8,19 @@ import (
 	"fmt"
 	"io"
 	"strings"
+	"time"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+const (
+	driveInspectRateLimitRetries    = 2
+	driveInspectRetryInitialBackoff = 200 * time.Millisecond
+)
+
+var driveInspectAfter = time.After
+
 var DriveInspect = common.Shortcut{
 	Service:           "drive",
 	Command:           "+inspect",
@@ -35,32 +43,15 @@ var DriveInspect = common.Shortcut{
 		},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		raw := strings.TrimSpace(runtime.Str("url"))
-		if raw == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--url cannot be empty").WithParam("--url")
-		}
-
-		_, ok := common.ParseResourceURL(raw)
-		if !ok {
-			// Not a recognized URL pattern.
-			if strings.Contains(raw, "://") {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --url %q: use a recognized Lark document URL or a bare token with --type", raw).WithParam("--url")
-			}
-			// Bare token: --type is required.
-			if strings.TrimSpace(runtime.Str("type")) == "" {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when --url is a bare token (allowed: doc, docx, sheet, bitable, wiki, file, folder, mindnote, slides)").WithParam("--type")
-			}
+		if _, err := driveInspectResolveRef(runtime); err != nil {
+			return err
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		raw := strings.TrimSpace(runtime.Str("url"))
-		ref, ok := common.ParseResourceURL(raw)
-		if !ok {
-			ref = common.ResourceRef{
-				Type:  strings.TrimSpace(runtime.Str("type")),
-				Token: raw,
-			}
+		ref, err := driveInspectResolveRef(runtime)
+		if err != nil {
+			return common.NewDryRunAPI()
 		}
 
 		dry := common.NewDryRunAPI()
@@ -91,15 +82,9 @@ var DriveInspect = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		raw := strings.TrimSpace(runtime.Str("url"))
-
-		// Step 1: Parse URL to extract {type, token}.
-		ref, ok := common.ParseResourceURL(raw)
-		if !ok {
-			// Bare token: use --type.
-			ref = common.ResourceRef{
-				Type:  strings.TrimSpace(runtime.Str("type")),
-				Token: raw,
-			}
+		ref, err := driveInspectResolveRef(runtime)
+		if err != nil {
+			return err
 		}
 
 		inputURL := raw
@@ -111,14 +96,19 @@ var DriveInspect = common.Shortcut{
 		// Step 2: If type is "wiki", unwrap via get_node API.
 		if docType == "wiki" {
 			fmt.Fprintf(runtime.IO().ErrOut, "Inspecting wiki node: %s\n", common.MaskToken(docToken))
-			data, err := runtime.CallAPITyped(
-				"GET",
-				"/open-apis/wiki/v2/spaces/get_node",
-				map[string]interface{}{"token": docToken},
-				nil,
+			data, err := driveInspectCallWithRetry(
+				ctx,
+				func() (map[string]interface{}, error) {
+					return runtime.CallAPITyped(
+						"GET",
+						"/open-apis/wiki/v2/spaces/get_node",
+						map[string]interface{}{"token": docToken},
+						nil,
+					)
+				},
 			)
 			if err != nil {
-				return err
+				return driveInspectAnnotateError("resolve_wiki", err)
 			}
 
 			node := common.GetMap(data, "node")
@@ -145,9 +135,9 @@ var DriveInspect = common.Shortcut{
 		}
 
 		// Step 3: Call batch_query to verify and get title.
-		title, err := common.FetchDriveMetaTitle(runtime, docToken, docType)
+		title, err := driveInspectFetchMetaTitle(ctx, runtime, docToken, docType)
 		if err != nil {
-			return err
+			return driveInspectAnnotateError("query_meta", err)
 		}
 
 		// Step 4: Build the resolved URL.
@@ -181,3 +171,116 @@ var DriveInspect = common.Shortcut{
 		return nil
 	},
 }
+
+func driveInspectResolveRef(runtime *common.RuntimeContext) (common.ResourceRef, error) {
+	raw := strings.TrimSpace(runtime.Str("url"))
+	if raw == "" {
+		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--url cannot be empty").WithParam("--url")
+	}
+
+	inputType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
+	ref, ok := common.ParseResourceURL(raw)
+	if ok {
+		if inputType != "" && inputType != ref.Type {
+			return common.ResourceRef{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				inputType,
+				ref.Type,
+			).WithParam("--type")
+		}
+		return ref, nil
+	}
+
+	if strings.Contains(raw, "://") {
+		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --url %q: use a recognized Lark document URL or a bare token with --type", raw).WithParam("--url")
+	}
+	if strings.ContainsAny(raw, "/?#") {
+		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid bare token %q: remove path/query fragments and pass only the raw token with --type", raw).WithParam("--url")
+	}
+	if inputType == "" {
+		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when --url is a bare token (allowed: doc, docx, sheet, bitable, wiki, file, folder, mindnote, slides)").WithParam("--type")
+	}
+	return common.ResourceRef{Type: inputType, Token: raw}, nil
+}
+
+func driveInspectFetchMetaTitle(ctx context.Context, runtime *common.RuntimeContext, token, docType string) (string, error) {
+	var title string
+	_, err := driveInspectCallWithRetry(ctx, func() (map[string]interface{}, error) {
+		got, callErr := common.FetchDriveMeta(runtime, token, docType, false)
+		if callErr != nil {
+			return nil, callErr
+		}
+		title = got.Title
+		return map[string]interface{}{"title": got.Title}, nil
+	})
+	if err != nil {
+		return "", err
+	}
+	return title, nil
+}
+
+func driveInspectCallWithRetry(ctx context.Context, call func() (map[string]interface{}, error)) (map[string]interface{}, error) {
+	var lastErr error
+	for attempt := 0; attempt <= driveInspectRateLimitRetries; attempt++ {
+		data, err := call()
+		if err == nil {
+			return data, nil
+		}
+		lastErr = err
+		if !driveInspectShouldRetry(err) || attempt == driveInspectRateLimitRetries {
+			return nil, err
+		}
+		backoff := driveInspectRetryInitialBackoff * time.Duration(1<<attempt)
+		if waitErr := driveInspectWait(ctx, backoff); waitErr != nil {
+			return nil, waitErr
+		}
+	}
+	return nil, lastErr
+}
+
+func driveInspectShouldRetry(err error) bool {
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem == nil {
+		return false
+	}
+	return problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400 || problem.Retryable
+}
+
+func driveInspectWait(ctx context.Context, d time.Duration) error {
+	if d <= 0 {
+		return nil
+	}
+	select {
+	case <-ctx.Done():
+		return errs.WrapInternal(ctx.Err())
+	case <-driveInspectAfter(d):
+		return nil
+	}
+}
+
+func driveInspectAnnotateError(stage string, err error) error {
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem == nil {
+		return err
+	}
+	label := map[string]string{
+		"resolve_wiki": "resolve wiki node",
+		"query_meta":   "query document metadata",
+	}[stage]
+	if label == "" {
+		label = stage
+	}
+	problem.Message = fmt.Sprintf("%s failed: %s", label, problem.Message)
+	if strings.TrimSpace(problem.Hint) == "" {
+		switch stage {
+		case "resolve_wiki":
+			problem.Hint = "check that the wiki URL/token is valid and that the current identity can read the wiki node"
+		case "query_meta":
+			problem.Hint = "check that the resolved document still exists and that the current identity can read its metadata"
+		}
+	} else if !strings.Contains(problem.Hint, label) {
+		problem.Hint = label + ": " + problem.Hint
+	}
+	return err
+}

shortcuts/drive/drive_inspect_test.go

@@ -6,10 +6,13 @@ package drive
 import (
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
+	"time"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -83,6 +86,34 @@ func TestDriveInspectValidate_BareTokenWithType(t *testing.T) {
 	}
 }
 
+func TestDriveInspectValidate_URLTypeConflict(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/docx/doxcnBareToken")
+	_ = cmd.Flags().Set("type", "sheet")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for conflicting --type, got nil")
+	}
+}
+
+func TestDriveInspectValidate_BareTokenWithPathFragment(t *testing.T) {
+	cmd := &cobra.Command{Use: "drive +inspect"}
+	cmd.Flags().String("url", "", "")
+	cmd.Flags().String("type", "", "")
+	_ = cmd.Flags().Set("url", "doxcnBareToken/extra")
+	_ = cmd.Flags().Set("type", "docx")
+
+	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
+	err := DriveInspect.Validate(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected error for bare token with path fragment, got nil")
+	}
+}
+
 func TestDriveInspectValidate_ValidDocxURL(t *testing.T) {
 	cmd := &cobra.Command{Use: "drive +inspect"}
 	cmd.Flags().String("url", "", "")
@@ -540,6 +571,76 @@ func TestDriveInspectExecute_BatchQueryError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for batch_query failure, got nil")
 	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T", err)
+	}
+	if !strings.Contains(p.Message, "query document metadata failed") {
+		t.Fatalf("message = %q, want query document metadata prefix", p.Message)
+	}
+}
+
+func TestDriveInspectExecute_RetriesRateLimitOnWikiResolve(t *testing.T) {
+	cfg := driveTestConfig()
+	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 99991400,
+			"msg":  "request trigger frequency limit",
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":   "docx",
+					"obj_token":  "doxcnUnwrapped",
+					"space_id":   "space123",
+					"node_token": "wikcnNodeToken",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "doxcnUnwrapped", "doc_type": "docx", "title": "Wiki Doc"},
+				},
+			},
+		},
+	})
+
+	origAfter := driveInspectAfter
+	driveInspectAfter = func(time.Duration) <-chan time.Time {
+		ch := make(chan time.Time, 1)
+		ch <- time.Now()
+		return ch
+	}
+	defer func() { driveInspectAfter = origAfter }()
+
+	err := mountAndRunDrive(t, DriveInspect, []string{
+		"+inspect",
+		"--url", "https://xxx.feishu.cn/wiki/wikcnABC",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error after retry: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	if data["token"] != "doxcnUnwrapped" {
+		t.Fatalf("token = %v, want doxcnUnwrapped", data["token"])
+	}
 }
 
 func TestDriveInspectExecute_PrettyFormat(t *testing.T) {

shortcuts/im/im_feed_group_item_test.go

@@ -424,6 +424,8 @@ func TestFeedGroupValidationErrors(t *testing.T) {
 		{"list missing feed-group-id", ImFeedGroupListItem, map[string]string{}, "--feed-group-id is required"},
 		{"list bad page-size", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "page-size": "0"}, "--page-size must be an integer between 1 and 50"},
 		{"list bad page-limit", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "page-limit": "2000"}, "--page-limit must be an integer between 1 and 1000"},
+		{"list bad start-time", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "start-time": "notnum"}, "--start-time must be Unix milliseconds"},
+		{"list bad end-time", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "end-time": "notnum"}, "--end-time must be Unix milliseconds"},
 		{"query missing feed-group-id", ImFeedGroupQueryItem, map[string]string{"feed-id": "oc_a"}, "--feed-group-id is required"},
 		{"query missing feed-id", ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x"}, "--feed-id is required (comma-separated chat IDs)"},
 		{"query blank feed-id tokens", ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x", "feed-id": ", ,"}, "--feed-id is required (comma-separated chat IDs)"},
@@ -446,7 +448,7 @@ func TestFeedGroupValidationErrors(t *testing.T) {
 
 func TestFeedGroupListItemDryRun(t *testing.T) {
 	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
-		"feed-group-id": "ofg_x", "page-size": "10", "start-time": "100",
+		"feed-group-id": "ofg_x", "page-size": "10", "page-token": "TKN", "start-time": "100", "end-time": "200",
 	}, nil, nil)
 	d := ImFeedGroupListItem.DryRun(context.Background(), runtime)
 	calls := dryRunCalls(t, d)
@@ -460,11 +462,12 @@ func TestFeedGroupListItemDryRun(t *testing.T) {
 		t.Errorf("url = %s", url)
 	}
 	params, _ := calls[0]["params"].(map[string]interface{})
-	if params["page_size"] != "10" {
-		t.Errorf("params page_size = %v, want 10", params["page_size"])
-	}
-	if params["start_time"] != "100" {
-		t.Errorf("params start_time = %v, want 100", params["start_time"])
+	for key, want := range map[string]string{
+		"page_size": "10", "page_token": "TKN", "start_time": "100", "end_time": "200",
+	} {
+		if params[key] != want {
+			t.Errorf("params %s = %v, want %s", key, params[key], want)
+		}
 	}
 	if desc, _ := calls[0]["desc"].(string); !strings.Contains(desc, "im:chat:read") {
 		t.Errorf("desc = %q, want chat_name enrichment note", desc)
@@ -514,3 +517,197 @@ func TestFeedGroupQueryItemDryRunValidationError(t *testing.T) {
 		t.Fatalf("expected error in dry-run output, got %#v", m)
 	}
 }
+
+// ── list-item: time-window flags reach the query ──
+
+func TestFeedGroupListItemTimeWindowQueryParams(t *testing.T) {
+	var reqs []recordedFGRequest
+	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
+		"feed-group-id": "ofg_x", "start-time": "100", "end-time": "200",
+	}, &reqs, func(path string, _ int) (int, interface{}) {
+		if strings.HasSuffix(path, "/list_item") {
+			return 200, wrapData(map[string]interface{}{
+				"items": []interface{}{}, "deleted_items": []interface{}{},
+				"page_token": "", "has_more": false,
+			})
+		}
+		return 200, wrapData(map[string]interface{}{})
+	})
+	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
+		t.Fatalf("Execute error: %v", err)
+	}
+	req := findFGRequest(reqs, "/list_item")
+	if req == nil {
+		t.Fatal("expected list_item request")
+	}
+	if got := firstQueryValue(req.query, "start_time"); got != "100" {
+		t.Errorf("start_time query = %q, want 100", got)
+	}
+	if got := firstQueryValue(req.query, "end_time"); got != "200" {
+		t.Errorf("end_time query = %q, want 200", got)
+	}
+}
+
+// ── list-item: infinite-loop guard + defensive page-limit clamping ──
+
+func TestFeedGroupListItemPageAllStopsOnRepeatedToken(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		pageLimit string
+	}{
+		{"limit clamped up from 0", "0"},
+		{"limit clamped down from 1001", "1001"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var reqs []recordedFGRequest
+			runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
+				"feed-group-id": "ofg_x", "page-all": "true", "page-limit": tc.pageLimit,
+				"start-time": "100", "end-time": "200",
+			}, &reqs, func(path string, _ int) (int, interface{}) {
+				if strings.HasSuffix(path, "/list_item") {
+					return 200, wrapData(map[string]interface{}{
+						"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1"}},
+						"deleted_items": []interface{}{},
+						"page_token":    "SAME", "has_more": true,
+					})
+				}
+				return 200, wrapData(map[string]interface{}{})
+			})
+			runtime.Format = "pretty" // exercise the page-all table-render path too
+			if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
+				t.Fatalf("Execute error: %v", err)
+			}
+			if got := countFGRequests(reqs, "/list_item"); got != 2 {
+				t.Errorf("expected 2 list_item requests (stop on repeated token), got %d", got)
+			}
+			errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
+			if !strings.Contains(errOut.String(), "page_token did not change") {
+				t.Errorf("stderr missing loop warning; got:\n%s", errOut.String())
+			}
+		})
+	}
+}
+
+// ── list-item: API errors surface from both Execute paths ──
+
+func TestFeedGroupListItemAPIError(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		flags map[string]string
+	}{
+		{"single page", map[string]string{"feed-group-id": "ofg_x"}},
+		{"page-all", map[string]string{"feed-group-id": "ofg_x", "page-all": "true"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			runtime := newFGRuntime(t, ImFeedGroupListItem, tc.flags, nil,
+				func(_ string, _ int) (int, interface{}) {
+					return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
+				})
+			if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err == nil {
+				t.Fatal("expected API error, got nil")
+			}
+		})
+	}
+}
+
+// ── enrichment: total resolution failure warns on stderr, nil data is a no-op ──
+
+func TestEnrichFeedGroupItemsWarnsWhenResolutionFails(t *testing.T) {
+	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{}, nil,
+		func(path string, _ int) (int, interface{}) {
+			if strings.HasSuffix(path, "/chats/batch_query") {
+				return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
+			}
+			return 200, wrapData(map[string]interface{}{})
+		})
+
+	// nil data must not panic.
+	enrichFeedGroupItemsChatName(runtime, nil)
+
+	data := map[string]any{
+		"items":         []any{map[string]any{"feed_id": "oc_a", "feed_type": "chat"}},
+		"deleted_items": []any{},
+	}
+	enrichFeedGroupItemsChatName(runtime, data)
+
+	item := data["items"].([]any)[0].(map[string]any)
+	if _, present := item["chat_name"]; present {
+		t.Errorf("chat_name should be absent when resolution fails, got %v", item["chat_name"])
+	}
+	errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
+	if !strings.Contains(errOut.String(), "could not resolve chat names") {
+		t.Errorf("stderr missing resolution warning; got:\n%s", errOut.String())
+	}
+}
+
+// ── query-item: Execute error paths ──
+
+func TestFeedGroupQueryItemExecuteErrors(t *testing.T) {
+	t.Run("invalid flags", func(t *testing.T) {
+		runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x"}, nil, nil)
+		if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err == nil {
+			t.Fatal("expected validation error from Execute, got nil")
+		}
+	})
+	t.Run("api error", func(t *testing.T) {
+		runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
+			"feed-group-id": "ofg_x", "feed-id": "oc_a",
+		}, nil, func(_ string, _ int) (int, interface{}) {
+			return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
+		})
+		if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err == nil {
+			t.Fatal("expected API error, got nil")
+		}
+	})
+}
+
+// ── formatFeedGroupUpdateTime: empty / non-numeric inputs pass through ──
+
+func TestFormatFeedGroupUpdateTime(t *testing.T) {
+	if got := formatFeedGroupUpdateTime(""); got != "" {
+		t.Errorf("empty input = %q, want empty passthrough", got)
+	}
+	if got := formatFeedGroupUpdateTime("not-millis"); got != "not-millis" {
+		t.Errorf("non-numeric input = %q, want raw passthrough", got)
+	}
+	want := time.UnixMilli(1767196800000).Local().Format(time.RFC3339)
+	if got := formatFeedGroupUpdateTime("1767196800000"); got != want {
+		t.Errorf("millis input = %q, want %q", got, want)
+	}
+}
+
+// ── query-item: pretty table output renders enriched items ──
+
+func TestFeedGroupQueryItemTableOutput(t *testing.T) {
+	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
+		"feed-group-id": "ofg_x", "feed-id": "oc_a",
+	}, nil, func(path string, _ int) (int, interface{}) {
+		switch {
+		case strings.HasSuffix(path, "/batch_query_item"):
+			return 200, wrapData(map[string]interface{}{
+				"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1767196800000"}},
+				"deleted_items": []interface{}{},
+			})
+		case strings.HasSuffix(path, "/chats/batch_query"):
+			return 200, wrapData(map[string]interface{}{"items": []interface{}{
+				map[string]interface{}{"chat_id": "oc_a", "name": "Team A"},
+			}})
+		}
+		return 200, wrapData(map[string]interface{}{})
+	})
+	runtime.Format = "pretty"
+
+	if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err != nil {
+		t.Fatalf("Execute error: %v", err)
+	}
+	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
+	if out == nil {
+		t.Fatal("stdout buffer missing")
+	}
+	got := out.String()
+	for _, want := range []string{"oc_a", "Team A", "1 item(s)"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("table output missing %q; got:\n%s", want, got)
+		}
+	}
+}

shortcuts/im/im_feed_group_list.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"strconv"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -57,7 +58,7 @@ var ImFeedGroupList = common.Shortcut{
 			return executeFeedGroupListGroupsAllPages(runtime)
 		}
 
-		data, err := runtime.DoAPIJSON("GET", feedGroupListPath, feedGroupListGroupsQuery(runtime), nil)
+		data, err := runtime.DoAPIJSONTyped("GET", feedGroupListPath, feedGroupListGroupsQuery(runtime), nil)
 		if err != nil {
 			return err
 		}
@@ -72,19 +73,19 @@ var ImFeedGroupList = common.Shortcut{
 
 func validateFeedGroupListPageOptions(rt *common.RuntimeContext) error {
 	if n := rt.Int("page-size"); n < 1 || n > 50 {
-		return output.ErrValidation("--page-size must be an integer between 1 and 50")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be an integer between 1 and 50").WithParam("--page-size")
 	}
 	if n := rt.Int("page-limit"); n < 1 || n > 1000 {
-		return output.ErrValidation("--page-limit must be an integer between 1 and 1000")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be an integer between 1 and 1000").WithParam("--page-limit")
 	}
 	if v := rt.Str("start-time"); v != "" {
 		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return output.ErrValidation("--start-time must be Unix milliseconds (a decimal integer string)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-time must be Unix milliseconds (a decimal integer string)").WithParam("--start-time")
 		}
 	}
 	if v := rt.Str("end-time"); v != "" {
 		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return output.ErrValidation("--end-time must be Unix milliseconds (a decimal integer string)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-time must be Unix milliseconds (a decimal integer string)").WithParam("--end-time")
 		}
 	}
 	return nil
@@ -158,7 +159,7 @@ func executeFeedGroupListGroupsAllPages(rt *common.RuntimeContext) error {
 			params["end_time"] = []string{end}
 		}
 
-		data, err := rt.DoAPIJSON("GET", feedGroupListPath, params, nil)
+		data, err := rt.DoAPIJSONTyped("GET", feedGroupListPath, params, nil)
 		if err != nil {
 			return err
 		}

shortcuts/im/im_feed_group_list_item.go

@@ -9,7 +9,7 @@ import (
 	"io"
 	"strconv"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -54,7 +54,7 @@ var ImFeedGroupListItem = common.Shortcut{
 			return executeFeedGroupListAllPages(runtime)
 		}
 
-		data, err := runtime.DoAPIJSON("GET", feedGroupListItemPath(runtime), feedGroupListQuery(runtime), nil)
+		data, err := runtime.DoAPIJSONTyped("GET", feedGroupListItemPath(runtime), feedGroupListQuery(runtime), nil)
 		if err != nil {
 			return err
 		}
@@ -70,22 +70,22 @@ var ImFeedGroupListItem = common.Shortcut{
 
 func validateFeedGroupListOptions(rt *common.RuntimeContext) error {
 	if rt.Str("feed-group-id") == "" {
-		return output.ErrValidation("--feed-group-id is required")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-group-id is required").WithParam("--feed-group-id")
 	}
 	if n := rt.Int("page-size"); n < 1 || n > 50 {
-		return output.ErrValidation("--page-size must be an integer between 1 and 50")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be an integer between 1 and 50").WithParam("--page-size")
 	}
 	if n := rt.Int("page-limit"); n < 1 || n > 1000 {
-		return output.ErrValidation("--page-limit must be an integer between 1 and 1000")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be an integer between 1 and 1000").WithParam("--page-limit")
 	}
 	if v := rt.Str("start-time"); v != "" {
 		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return output.ErrValidation("--start-time must be Unix milliseconds (a decimal integer string)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-time must be Unix milliseconds (a decimal integer string)").WithParam("--start-time")
 		}
 	}
 	if v := rt.Str("end-time"); v != "" {
 		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return output.ErrValidation("--end-time must be Unix milliseconds (a decimal integer string)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-time must be Unix milliseconds (a decimal integer string)").WithParam("--end-time")
 		}
 	}
 	return nil
@@ -163,7 +163,7 @@ func executeFeedGroupListAllPages(rt *common.RuntimeContext) error {
 			params["end_time"] = []string{end}
 		}
 
-		data, err := rt.DoAPIJSON("GET", feedGroupListItemPath(rt), params, nil)
+		data, err := rt.DoAPIJSONTyped("GET", feedGroupListItemPath(rt), params, nil)
 		if err != nil {
 			return err
 		}

shortcuts/im/im_feed_group_list_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 )
 
@@ -102,6 +103,7 @@ func TestFeedGroupListValidation(t *testing.T) {
 		{"page-size too large", map[string]string{"page-size": "51"}, "--page-size"},
 		{"page-limit too large", map[string]string{"page-limit": "1001"}, "--page-limit"},
 		{"bad start-time", map[string]string{"start-time": "notnum"}, "--start-time"},
+		{"bad end-time", map[string]string{"end-time": "notnum"}, "--end-time"},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
@@ -116,3 +118,140 @@ func TestFeedGroupListValidation(t *testing.T) {
 		})
 	}
 }
+
+// TestFeedGroupListSinglePageTableOutput covers the non-page-all Execute path:
+// time-window params must reach the query, and the pretty table must render
+// group_id / name / type with the summary, pagination hint and deleted count.
+func TestFeedGroupListSinglePageTableOutput(t *testing.T) {
+	var reqs []recordedFGRequest
+	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
+		"start-time": "100", "end-time": "200",
+	}, &reqs, func(_ string, _ int) (int, interface{}) {
+		return 200, wrapData(map[string]interface{}{
+			"groups":         []interface{}{fgGroup("g1"), fgGroup("g2")},
+			"deleted_groups": []interface{}{fgGroup("d1")},
+			"page_token":     "TKN", "has_more": true,
+		})
+	})
+	runtime.Format = "pretty"
+
+	if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
+		t.Fatalf("Execute: %v", err)
+	}
+	if got := countFGRequests(reqs, "/groups"); got != 1 {
+		t.Fatalf("expected 1 groups request, got %d", got)
+	}
+	if got := firstQueryValue(reqs[0].query, "start_time"); got != "100" {
+		t.Errorf("start_time query = %q, want 100", got)
+	}
+	if got := firstQueryValue(reqs[0].query, "end_time"); got != "200" {
+		t.Errorf("end_time query = %q, want 200", got)
+	}
+
+	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
+	if out == nil {
+		t.Fatal("stdout buffer missing")
+	}
+	got := out.String()
+	for _, want := range []string{"group_id", "g1", "g2", "2 group(s)", "more available", "(1 deleted)"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("table output missing %q; got:\n%s", want, got)
+		}
+	}
+}
+
+// TestFeedGroupListDryRun locks the dry-run shape: GET /groups with page_size,
+// page_token (always present) and the optional time-window params.
+func TestFeedGroupListDryRun(t *testing.T) {
+	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
+		"page-size": "10", "page-token": "TKN", "start-time": "100", "end-time": "200",
+	}, nil, nil)
+	d := ImFeedGroupList.DryRun(context.Background(), runtime)
+	calls := dryRunCalls(t, d)
+	if len(calls) != 1 {
+		t.Fatalf("expected 1 call, got %d", len(calls))
+	}
+	if calls[0]["method"] != "GET" {
+		t.Errorf("method = %v, want GET", calls[0]["method"])
+	}
+	if url, _ := calls[0]["url"].(string); !strings.HasSuffix(url, "/open-apis/im/v1/groups") {
+		t.Errorf("url = %s", url)
+	}
+	params, _ := calls[0]["params"].(map[string]interface{})
+	for key, want := range map[string]string{
+		"page_size": "10", "page_token": "TKN", "start_time": "100", "end_time": "200",
+	} {
+		if params[key] != want {
+			t.Errorf("params %s = %v, want %s", key, params[key], want)
+		}
+	}
+}
+
+func TestFeedGroupListDryRunValidationError(t *testing.T) {
+	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{"page-size": "0"}, nil, nil)
+	d := ImFeedGroupList.DryRun(context.Background(), runtime)
+	m := dryRunJSON(t, d)
+	errMsg, _ := m["error"].(string)
+	if !strings.Contains(errMsg, "--page-size") {
+		t.Errorf("dry-run error = %q, want --page-size validation message", errMsg)
+	}
+}
+
+// TestFeedGroupListPageAllStopsOnRepeatedToken locks the infinite-loop guard:
+// when the server keeps returning the same page_token with has_more=true,
+// pagination must stop after the repeat and warn on stderr. Also exercises the
+// defensive page-limit clamping (Execute is called directly, bypassing Validate).
+func TestFeedGroupListPageAllStopsOnRepeatedToken(t *testing.T) {
+	for _, tc := range []struct {
+		name      string
+		pageLimit string
+	}{
+		{"limit clamped up from 0", "0"},
+		{"limit clamped down from 1001", "1001"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var reqs []recordedFGRequest
+			runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
+				"page-all": "true", "page-limit": tc.pageLimit, "start-time": "100", "end-time": "200",
+			}, &reqs, func(_ string, _ int) (int, interface{}) {
+				return 200, wrapData(map[string]interface{}{
+					"groups":         []interface{}{fgGroup("g1")},
+					"deleted_groups": []interface{}{},
+					"page_token":     "SAME", "has_more": true,
+				})
+			})
+			runtime.Format = "pretty" // exercise the page-all table-render path too
+			if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
+				t.Fatalf("Execute: %v", err)
+			}
+			if got := countFGRequests(reqs, "/groups"); got != 2 {
+				t.Errorf("expected 2 requests (stop on repeated token), got %d", got)
+			}
+			errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
+			if !strings.Contains(errOut.String(), "page_token did not change") {
+				t.Errorf("stderr missing loop warning; got:\n%s", errOut.String())
+			}
+		})
+	}
+}
+
+// TestFeedGroupListAPIError checks both Execute paths surface API errors.
+func TestFeedGroupListAPIError(t *testing.T) {
+	for _, tc := range []struct {
+		name  string
+		flags map[string]string
+	}{
+		{"single page", map[string]string{}},
+		{"page-all", map[string]string{"page-all": "true"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			runtime := newFGRuntime(t, ImFeedGroupList, tc.flags, nil,
+				func(_ string, _ int) (int, interface{}) {
+					return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
+				})
+			if err := ImFeedGroupList.Execute(context.Background(), runtime); err == nil {
+				t.Fatal("expected API error, got nil")
+			}
+		})
+	}
+}

shortcuts/im/im_feed_group_query_item.go

@@ -7,7 +7,7 @@ import (
 	"context"
 	"io"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -47,7 +47,7 @@ var ImFeedGroupQueryItem = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.DoAPIJSON("POST", feedGroupQueryItemPath(runtime), nil, body)
+		data, err := runtime.DoAPIJSONTyped("POST", feedGroupQueryItemPath(runtime), nil, body)
 		if err != nil {
 			return err
 		}
@@ -70,7 +70,7 @@ func feedGroupQueryItemPath(rt *common.RuntimeContext) string {
 // {"items":[{"feed_id":"<tok>","feed_type":"chat"}, ...]}.
 func buildFeedGroupQueryItemBody(rt *common.RuntimeContext) (map[string]any, error) {
 	if rt.Str("feed-group-id") == "" {
-		return nil, output.ErrValidation("--feed-group-id is required")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-group-id is required").WithParam("--feed-group-id")
 	}
 	tokens := common.SplitCSV(rt.Str("feed-id"))
 	items := make([]any, 0, len(tokens))
@@ -84,7 +84,7 @@ func buildFeedGroupQueryItemBody(rt *common.RuntimeContext) (map[string]any, err
 		})
 	}
 	if len(items) == 0 {
-		return nil, output.ErrValidation("--feed-id is required (comma-separated chat IDs)")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-id is required (comma-separated chat IDs)").WithParam("--feed-id")
 	}
 	return map[string]any{"items": items}, nil
 }

shortcuts/markdown/helpers.go

@@ -6,18 +6,18 @@ package markdown
 import (
 	"bytes"
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"path"
 	"path/filepath"
 	"strings"
+	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/client"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -28,8 +28,17 @@ const markdownEmptyContentError = "empty markdown content is not supported; cann
 const (
 	markdownUploadParentTypeExplorer = "explorer"
 	markdownUploadParentTypeWiki     = "wiki"
+	markdownUploadAllAction          = "upload markdown file failed"
+	markdownUploadPrepareAction      = "initialize markdown multipart upload failed"
+	markdownUploadFinishAction       = "finalize markdown multipart upload failed"
+	markdownFetchNameAction          = "fetch existing markdown file name failed"
 )
 
+var markdownUploadRetryBackoffs = []time.Duration{
+	200 * time.Millisecond,
+	500 * time.Millisecond,
+}
+
 type markdownUploadSpec struct {
 	FileToken   string
 	FileName    string
@@ -74,16 +83,18 @@ func (spec markdownUploadSpec) Target() markdownUploadTarget {
 func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpec, requireName bool) error {
 	switch {
 	case spec.ContentSet && spec.FileSet:
-		return common.FlagErrorf("--content and --file are mutually exclusive")
+		return markdownValidationError("--content and --file are mutually exclusive").
+			WithParams(markdownInvalidParam("--content", "mutually exclusive"), markdownInvalidParam("--file", "mutually exclusive"))
 	case !spec.ContentSet && !spec.FileSet:
-		return common.FlagErrorf("specify exactly one of --content or --file")
+		return markdownValidationError("specify exactly one of --content or --file").
+			WithParams(markdownInvalidParam("--content", "required; specify exactly one"), markdownInvalidParam("--file", "required; specify exactly one"))
 	}
 
 	if markdownFlagExplicitlyEmpty(runtime, "folder-token") {
-		return common.FlagErrorf("--folder-token cannot be empty; omit it to upload into Drive root folder")
+		return markdownValidationParamError("--folder-token", "--folder-token cannot be empty; omit it to upload into Drive root folder")
 	}
 	if markdownFlagExplicitlyEmpty(runtime, "wiki-token") {
-		return common.FlagErrorf("--wiki-token cannot be empty; provide a valid wiki node token or omit the flag entirely")
+		return markdownValidationParamError("--wiki-token", "--wiki-token cannot be empty; provide a valid wiki node token or omit the flag entirely")
 	}
 	targets := 0
 	if spec.FolderToken != "" {
@@ -93,22 +104,23 @@ func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpe
 		targets++
 	}
 	if targets > 1 {
-		return common.FlagErrorf("--folder-token and --wiki-token are mutually exclusive")
+		return markdownValidationError("--folder-token and --wiki-token are mutually exclusive").
+			WithParams(markdownInvalidParam("--folder-token", "mutually exclusive"), markdownInvalidParam("--wiki-token", "mutually exclusive"))
 	}
 	if spec.FolderToken != "" {
 		if err := validate.ResourceName(spec.FolderToken, "--folder-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--folder-token", "%s", err).WithCause(err)
 		}
 	}
 	if spec.WikiToken != "" {
 		if err := validate.ResourceName(spec.WikiToken, "--wiki-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--wiki-token", "%s", err).WithCause(err)
 		}
 	}
 
 	if requireName && spec.ContentSet {
 		if strings.TrimSpace(spec.FileName) == "" {
-			return common.FlagErrorf("--name is required when using --content")
+			return markdownValidationParamError("--name", "--name is required when using --content")
 		}
 		if err := validateMarkdownFileName(spec.FileName, "--name"); err != nil {
 			return err
@@ -117,10 +129,10 @@ func validateMarkdownSpec(runtime *common.RuntimeContext, spec markdownUploadSpe
 
 	if spec.FileSet {
 		if strings.TrimSpace(spec.FilePath) == "" {
-			return common.FlagErrorf("--file cannot be empty")
+			return markdownValidationParamError("--file", "--file cannot be empty")
 		}
 		if _, err := validate.SafeInputPath(spec.FilePath); err != nil {
-			return output.ErrValidation("unsafe file path: %s", err)
+			return markdownValidationParamError("--file", "unsafe file path: %s", err).WithCause(err)
 		}
 		if err := validateMarkdownFileName(filepath.Base(spec.FilePath), "--file"); err != nil {
 			return err
@@ -143,10 +155,10 @@ func markdownFlagExplicitlyEmpty(runtime *common.RuntimeContext, flagName string
 func validateMarkdownFileName(name, flagName string) error {
 	trimmed := strings.TrimSpace(name)
 	if trimmed == "" {
-		return common.FlagErrorf("%s cannot be empty", flagName)
+		return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
 	}
 	if !strings.HasSuffix(strings.ToLower(trimmed), ".md") {
-		return common.FlagErrorf("%s must end with .md", flagName)
+		return markdownValidationParamError(flagName, "%s must end with .md", flagName)
 	}
 	return nil
 }
@@ -190,22 +202,9 @@ func openMarkdownDownload(ctx context.Context, runtime *common.RuntimeContext, f
 	return resp, nil
 }
 
-func wrapMarkdownDownloadError(err error) error {
-	// Preserve any already-classified error: legacy *output.ExitError or any
-	// typed errs.* error. Only un-classified errors get wrapped as network.
-	var exitErr *output.ExitError
-	if errors.As(err, &exitErr) {
-		return err
-	}
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	return output.ErrNetwork("download failed: %s", err)
-}
-
 func validateNonEmptyMarkdownSize(size int64) error {
 	if size == 0 {
-		return output.ErrValidation("%s", markdownEmptyContentError)
+		return markdownValidationError("%s", markdownEmptyContentError)
 	}
 	return nil
 }
@@ -216,12 +215,12 @@ func markdownSourceSize(runtime *common.RuntimeContext, spec markdownUploadSpec)
 		size = int64(len(spec.Content))
 	} else {
 		if strings.TrimSpace(spec.FilePath) == "" {
-			return 0, common.FlagErrorf("--file cannot be empty")
+			return 0, markdownValidationParamError("--file", "--file cannot be empty")
 		}
 
 		info, err := runtime.FileIO().Stat(spec.FilePath)
 		if err != nil {
-			return 0, common.WrapInputStatError(err)
+			return 0, common.WrapInputStatErrorTyped(err)
 		}
 		size = info.Size()
 	}
@@ -387,58 +386,68 @@ func uploadMarkdownContent(runtime *common.RuntimeContext, spec markdownUploadSp
 	fileName := finalMarkdownFileName(spec)
 	fileSize := int64(len(payload))
 	if fileSize > markdownSinglePartSizeLimit {
-		return uploadMarkdownFileMultipart(runtime, spec, bytes.NewReader(payload), fileName, fileSize)
+		return uploadMarkdownFileMultipart(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
+			return io.NopCloser(bytes.NewReader(payload)), nil
+		})
 	}
-	return uploadMarkdownFileAll(runtime, spec, bytes.NewReader(payload), fileName, fileSize)
+	return uploadMarkdownFileAll(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
+		return io.NopCloser(bytes.NewReader(payload)), nil
+	})
 }
 
 func uploadMarkdownLocalFile(runtime *common.RuntimeContext, spec markdownUploadSpec, fileSize int64) (markdownUploadResult, error) {
 	fileName := finalMarkdownFileName(spec)
-	f, err := runtime.FileIO().Open(spec.FilePath)
-	if err != nil {
-		return markdownUploadResult{}, common.WrapInputStatError(err)
-	}
-	defer f.Close()
-
 	if fileSize > markdownSinglePartSizeLimit {
-		return uploadMarkdownFileMultipart(runtime, spec, f, fileName, fileSize)
+		return uploadMarkdownFileMultipart(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
+			return runtime.FileIO().Open(spec.FilePath)
+		})
 	}
-	return uploadMarkdownFileAll(runtime, spec, f, fileName, fileSize)
+	return uploadMarkdownFileAll(runtime, spec, fileName, fileSize, func() (io.ReadCloser, error) {
+		return runtime.FileIO().Open(spec.FilePath)
+	})
 }
 
-func uploadMarkdownFileAll(runtime *common.RuntimeContext, spec markdownUploadSpec, fileReader io.Reader, fileName string, fileSize int64) (markdownUploadResult, error) {
+func uploadMarkdownFileAll(runtime *common.RuntimeContext, spec markdownUploadSpec, fileName string, fileSize int64, openReader func() (io.ReadCloser, error)) (markdownUploadResult, error) {
 	target := spec.Target()
-	fd := larkcore.NewFormdata()
-	fd.AddField("file_name", fileName)
-	fd.AddField("parent_type", target.ParentType)
-	fd.AddField("parent_node", target.ParentNode)
-	fd.AddField("size", fmt.Sprintf("%d", fileSize))
-	if spec.FileToken != "" {
-		fd.AddField("file_token", spec.FileToken)
-	}
-	fd.AddFile("file", fileReader)
-
-	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-		HttpMethod: http.MethodPost,
-		ApiPath:    "/open-apis/drive/v1/files/upload_all",
-		Body:       fd,
-	}, larkcore.WithFileUpload())
-	if err != nil {
-		var exitErr *output.ExitError
-		if errors.As(err, &exitErr) {
-			return markdownUploadResult{}, err
+	return withMarkdownUploadRetryResult(runtime, markdownUploadAllAction, func() (markdownUploadResult, error) {
+		fileReader, err := openReader()
+		if err != nil {
+			return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
 		}
-		return markdownUploadResult{}, output.ErrNetwork("upload failed: %v", err)
-	}
+		defer fileReader.Close()
 
-	data, err := common.ParseDriveMediaUploadResponse(apiResp, "upload failed")
-	if err != nil {
-		return markdownUploadResult{}, err
-	}
-	return parseMarkdownUploadResult(data, spec.FileToken != "")
+		fd := larkcore.NewFormdata()
+		fd.AddField("file_name", fileName)
+		fd.AddField("parent_type", target.ParentType)
+		fd.AddField("parent_node", target.ParentNode)
+		fd.AddField("size", fmt.Sprintf("%d", fileSize))
+		if spec.FileToken != "" {
+			fd.AddField("file_token", spec.FileToken)
+		}
+		fd.AddFile("file", fileReader)
+
+		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+			HttpMethod: http.MethodPost,
+			ApiPath:    "/open-apis/drive/v1/files/upload_all",
+			Body:       fd,
+		}, larkcore.WithFileUpload())
+		if err != nil {
+			return markdownUploadResult{}, markdownUploadProblem(client.WrapDoAPIError(err), markdownUploadAllAction)
+		}
+
+		data, err := runtime.ClassifyAPIResponse(apiResp)
+		if err != nil {
+			return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadAllAction)
+		}
+		result, err := parseMarkdownUploadResult(data, spec.FileToken != "")
+		if err != nil {
+			return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadAllAction)
+		}
+		return result, nil
+	})
 }
 
-func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUploadSpec, fileReader io.Reader, fileName string, fileSize int64) (markdownUploadResult, error) {
+func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUploadSpec, fileName string, fileSize int64, openReader func() (io.ReadCloser, error)) (markdownUploadResult, error) {
 	target := spec.Target()
 	prepareBody := map[string]interface{}{
 		"file_name":   fileName,
@@ -450,31 +459,53 @@ func uploadMarkdownFileMultipart(runtime *common.RuntimeContext, spec markdownUp
 		prepareBody["file_token"] = spec.FileToken
 	}
 
-	prepareResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_prepare", nil, prepareBody)
+	prepareResult, err := withMarkdownUploadRetryData(runtime, markdownUploadPrepareAction, func() (map[string]interface{}, error) {
+		data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/files/upload_prepare", nil, prepareBody)
+		if err != nil {
+			return nil, markdownUploadProblem(err, markdownUploadPrepareAction)
+		}
+		return data, nil
+	})
 	if err != nil {
 		return markdownUploadResult{}, err
 	}
 
 	session, err := parseMarkdownMultipartSession(prepareResult)
 	if err != nil {
-		return markdownUploadResult{}, err
+		return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadPrepareAction)
 	}
 
 	fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload initialized: %d chunks x %s\n", session.BlockNum, common.FormatSize(session.BlockSize))
 
+	fileReader, err := openReader()
+	if err != nil {
+		return markdownUploadResult{}, common.WrapInputStatErrorTyped(err)
+	}
+	defer fileReader.Close()
+
 	if err := uploadMarkdownMultipartParts(runtime, fileReader, fileSize, session); err != nil {
 		return markdownUploadResult{}, err
 	}
 
-	finishResult, err := runtime.CallAPI("POST", "/open-apis/drive/v1/files/upload_finish", nil, map[string]interface{}{
-		"upload_id": session.UploadID,
-		"block_num": session.BlockNum,
+	finishResult, err := withMarkdownUploadRetryData(runtime, markdownUploadFinishAction, func() (map[string]interface{}, error) {
+		data, err := runtime.CallAPITyped("POST", "/open-apis/drive/v1/files/upload_finish", nil, map[string]interface{}{
+			"upload_id": session.UploadID,
+			"block_num": session.BlockNum,
+		})
+		if err != nil {
+			return nil, markdownUploadProblem(err, markdownUploadFinishAction)
+		}
+		return data, nil
 	})
 	if err != nil {
 		return markdownUploadResult{}, err
 	}
 
-	return parseMarkdownUploadResult(finishResult, spec.FileToken != "")
+	result, err := parseMarkdownUploadResult(finishResult, spec.FileToken != "")
+	if err != nil {
+		return markdownUploadResult{}, markdownUploadProblem(err, markdownUploadFinishAction)
+	}
+	return result, nil
 }
 
 func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipartSession, error) {
@@ -484,7 +515,7 @@ func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipa
 		BlockNum:  int(common.GetFloat(data, "block_num")),
 	}
 	if session.UploadID == "" || session.BlockSize <= 0 || session.BlockNum <= 0 {
-		return markdownMultipartSession{}, output.Errorf(output.ExitAPI, "api_error",
+		return markdownMultipartSession{}, errs.NewInternalError(errs.SubtypeInvalidResponse,
 			"upload_prepare returned invalid data: upload_id=%q, block_size=%d, block_num=%d",
 			session.UploadID, session.BlockSize, session.BlockNum)
 	}
@@ -494,9 +525,8 @@ func parseMarkdownMultipartSession(data map[string]interface{}) (markdownMultipa
 func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.Reader, payloadSize int64, session markdownMultipartSession) error {
 	expectedBlocks := int((payloadSize + session.BlockSize - 1) / session.BlockSize)
 	if session.BlockNum != expectedBlocks {
-		return output.Errorf(
-			output.ExitAPI,
-			"api_error",
+		return errs.NewInternalError(
+			errs.SubtypeInvalidResponse,
 			"upload_prepare returned inconsistent chunk plan: block_size=%d, block_num=%d, expected_block_num=%d, payload_size=%d",
 			session.BlockSize,
 			session.BlockNum,
@@ -507,7 +537,7 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 
 	maxInt := int64(^uint(0) >> 1)
 	if session.BlockSize > maxInt {
-		return output.Errorf(output.ExitAPI, "api_error", "upload prepare failed: invalid block_size returned")
+		return errs.NewInternalError(errs.SubtypeInvalidResponse, "upload prepare failed: invalid block_size returned")
 	}
 
 	buffer := make([]byte, int(session.BlockSize))
@@ -521,29 +551,34 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 
 		n, readErr := io.ReadFull(fileReader, buffer[:int(chunkSize)])
 		if readErr != nil {
-			return output.ErrValidation("cannot read file: %s", readErr)
+			return markdownValidationError("cannot read file: %s", readErr).WithCause(readErr)
 		}
 
 		fd := larkcore.NewFormdata()
 		fd.AddField("upload_id", session.UploadID)
 		fd.AddField("seq", fmt.Sprintf("%d", seq))
 		fd.AddField("size", fmt.Sprintf("%d", n))
-		fd.AddFile("file", bytes.NewReader(buffer[:n]))
+		action := fmt.Sprintf("upload markdown file part %d/%d failed", seq+1, session.BlockNum)
+		if err := withMarkdownUploadRetryVoid(runtime, action, func() error {
+			fd := larkcore.NewFormdata()
+			fd.AddField("upload_id", session.UploadID)
+			fd.AddField("seq", fmt.Sprintf("%d", seq))
+			fd.AddField("size", fmt.Sprintf("%d", n))
+			fd.AddFile("file", bytes.NewReader(buffer[:n]))
 
-		apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
-			HttpMethod: http.MethodPost,
-			ApiPath:    "/open-apis/drive/v1/files/upload_part",
-			Body:       fd,
-		}, larkcore.WithFileUpload())
-		if err != nil {
-			var exitErr *output.ExitError
-			if errors.As(err, &exitErr) {
-				return err
+			apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+				HttpMethod: http.MethodPost,
+				ApiPath:    "/open-apis/drive/v1/files/upload_part",
+				Body:       fd,
+			}, larkcore.WithFileUpload())
+			if err != nil {
+				return markdownUploadProblem(client.WrapDoAPIError(err), action)
 			}
-			return output.ErrNetwork("upload part %d/%d failed: %v", seq+1, session.BlockNum, err)
-		}
-
-		if _, err := common.ParseDriveMediaUploadResponse(apiResp, fmt.Sprintf("upload part %d/%d failed", seq+1, session.BlockNum)); err != nil {
+			if _, err := runtime.ClassifyAPIResponse(apiResp); err != nil {
+				return markdownUploadProblem(err, action)
+			}
+			return nil
+		}); err != nil {
 			return err
 		}
 
@@ -551,9 +586,8 @@ func uploadMarkdownMultipartParts(runtime *common.RuntimeContext, fileReader io.
 		remaining -= int64(n)
 	}
 	if remaining != 0 {
-		return output.Errorf(
-			output.ExitAPI,
-			"api_error",
+		return errs.NewInternalError(
+			errs.SubtypeInvalidResponse,
 			"upload_prepare returned inconsistent chunk plan: %d bytes remain after %d blocks",
 			remaining,
 			session.BlockNum,
@@ -572,28 +606,34 @@ func parseMarkdownUploadResult(data map[string]interface{}, requireVersion bool)
 		result.Version = common.GetString(data, "data_version")
 	}
 	if result.FileToken == "" {
-		return markdownUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "upload failed: no file_token returned")
+		return markdownUploadResult{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "upload failed: no file_token returned")
 	}
 	if requireVersion && result.Version == "" {
-		return markdownUploadResult{}, output.Errorf(output.ExitAPI, "api_error", "overwrite failed: no version returned")
+		return markdownUploadResult{}, errs.NewInternalError(errs.SubtypeInvalidResponse, "overwrite failed: no version returned")
 	}
 	return result, nil
 }
 
 func fetchMarkdownFileName(runtime *common.RuntimeContext, fileToken string) (string, error) {
-	data, err := runtime.CallAPI(
-		"POST",
-		"/open-apis/drive/v1/metas/batch_query",
-		nil,
-		map[string]interface{}{
-			"request_docs": []map[string]interface{}{
-				{
-					"doc_token": fileToken,
-					"doc_type":  "file",
+	data, err := withMarkdownUploadRetryData(runtime, markdownFetchNameAction, func() (map[string]interface{}, error) {
+		data, err := runtime.CallAPITyped(
+			"POST",
+			"/open-apis/drive/v1/metas/batch_query",
+			nil,
+			map[string]interface{}{
+				"request_docs": []map[string]interface{}{
+					{
+						"doc_token": fileToken,
+						"doc_type":  "file",
+					},
 				},
 			},
-		},
-	)
+		)
+		if err != nil {
+			return nil, markdownUploadProblem(err, markdownFetchNameAction)
+		}
+		return data, nil
+	})
 	if err != nil {
 		return "", err
 	}
@@ -606,6 +646,97 @@ func fetchMarkdownFileName(runtime *common.RuntimeContext, fileToken string) (st
 	return common.GetString(meta, "title"), nil
 }
 
+func withMarkdownUploadRetryResult(runtime *common.RuntimeContext, action string, fn func() (markdownUploadResult, error)) (markdownUploadResult, error) {
+	var zero markdownUploadResult
+	for attempt := 0; ; attempt++ {
+		result, err := fn()
+		if err == nil {
+			return result, nil
+		}
+		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
+			return zero, markdownUploadRetryExhausted(err, action, attempt)
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
+		time.Sleep(markdownUploadRetryBackoffs[attempt])
+	}
+}
+
+func withMarkdownUploadRetryData(runtime *common.RuntimeContext, action string, fn func() (map[string]interface{}, error)) (map[string]interface{}, error) {
+	for attempt := 0; ; attempt++ {
+		result, err := fn()
+		if err == nil {
+			return result, nil
+		}
+		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
+			return nil, markdownUploadRetryExhausted(err, action, attempt)
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
+		time.Sleep(markdownUploadRetryBackoffs[attempt])
+	}
+}
+
+func withMarkdownUploadRetryVoid(runtime *common.RuntimeContext, action string, fn func() error) error {
+	for attempt := 0; ; attempt++ {
+		err := fn()
+		if err == nil {
+			return nil
+		}
+		if !markdownUploadShouldRetry(err) || attempt >= len(markdownUploadRetryBackoffs) {
+			return markdownUploadRetryExhausted(err, action, attempt)
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "%s; retrying (attempt %d/%d)\n", err.Error(), attempt+1, len(markdownUploadRetryBackoffs))
+		time.Sleep(markdownUploadRetryBackoffs[attempt])
+	}
+}
+
+func markdownUploadShouldRetry(err error) bool {
+	p, ok := errs.ProblemOf(err)
+	if !ok || p == nil {
+		return false
+	}
+	return p.Retryable || p.Category == errs.CategoryNetwork
+}
+
+func markdownUploadRetryExhausted(err error, action string, retries int) error {
+	if retries <= 0 {
+		return err
+	}
+	return appendMarkdownProblemHint(err, fmt.Sprintf("%s remained retryable after %d attempts; retry later if the upstream service is throttling or temporarily unavailable", action, retries+1))
+}
+
+func markdownUploadProblem(err error, action string) error {
+	if p, ok := errs.ProblemOf(err); ok {
+		p.Message = action + ": " + p.Message
+		switch p.Code {
+		case 99991672, 99991679:
+			appendMarkdownProblemHint(err, "The current token or identity lacks the required document upload scope/capability. Grant the document upload scope or use a token with the appropriate permissions, then retry.")
+		case 10071:
+			appendMarkdownProblemHint(err, "The target document has reached its version limit. Clean up old versions or create a new file before retrying.")
+		case 90003087:
+			appendMarkdownProblemHint(err, "The current tenant or user may not have document capabilities enabled. Ask an administrator to verify document-module access.")
+		case 1061003, 1061044:
+			appendMarkdownProblemHint(err, "Check whether the target folder or wiki node still exists, and verify the token you passed to the command.")
+		case 1061004, 1062501:
+			appendMarkdownProblemHint(err, "Check whether the current identity has write access to the target folder or wiki node.")
+		}
+	}
+	return err
+}
+
+func appendMarkdownProblemHint(err error, hint string) error {
+	if strings.TrimSpace(hint) == "" {
+		return err
+	}
+	if p, ok := errs.ProblemOf(err); ok {
+		if strings.TrimSpace(p.Hint) != "" {
+			p.Hint = p.Hint + "\n" + hint
+		} else {
+			p.Hint = hint
+		}
+	}
+	return err
+}
+
 func prettyPrintMarkdownWrite(w io.Writer, data map[string]interface{}) {
 	fmt.Fprintf(w, "file_token: %s\n", common.GetString(data, "file_token"))
 	fmt.Fprintf(w, "file_name: %s\n", common.GetString(data, "file_name"))

shortcuts/markdown/markdown_diff.go

@@ -5,7 +5,6 @@ package markdown
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"io"
 	"regexp"
@@ -14,6 +13,7 @@ import (
 
 	"github.com/sergi/go-diff/diffmatchpatch"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -65,7 +65,7 @@ type markdownDiffHunkRange struct {
 
 func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffSpec) error {
 	if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
-		return output.ErrValidation("%s", err)
+		return markdownValidationParamError("--file-token", "%s", err).WithCause(err)
 	}
 	if spec.FromVersion != "" {
 		if err := validateMarkdownDiffVersionValue(spec.FromVersion, "--from-version"); err != nil {
@@ -79,29 +79,29 @@ func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffS
 	}
 	if spec.FilePath != "" {
 		if _, err := validate.SafeInputPath(spec.FilePath); err != nil {
-			return output.ErrValidation("unsafe file path: %s", err)
+			return markdownValidationParamError("--file", "unsafe file path: %s", err).WithCause(err)
 		}
 		if err := validateMarkdownFileName(spec.FilePath, "--file"); err != nil {
 			return err
 		}
 	}
 	if spec.ContextLines < 0 {
-		return output.ErrValidation("--context-lines must be >= 0")
+		return markdownValidationParamError("--context-lines", "--context-lines must be >= 0")
 	}
 	if spec.Format != "" && spec.Format != "json" && spec.Format != "pretty" {
-		return output.ErrValidation("markdown +diff only supports --format json or pretty")
+		return markdownValidationParamError("--format", "markdown +diff only supports --format json or pretty")
 	}
 	if spec.FilePath == "" {
 		if spec.FromVersion == "" && spec.ToVersion == "" {
-			return common.FlagErrorf("specify --from-version, or both --from-version and --to-version, or use --file for remote vs local diff")
+			return markdownValidationError("specify --from-version, or both --from-version and --to-version, or use --file for remote vs local diff")
 		}
 		if spec.FromVersion == "" && spec.ToVersion != "" {
-			return common.FlagErrorf("--to-version requires --from-version")
+			return markdownValidationParamError("--to-version", "--to-version requires --from-version")
 		}
 		return nil
 	}
 	if spec.ToVersion != "" {
-		return common.FlagErrorf("--to-version is not supported together with --file")
+		return markdownValidationParamError("--to-version", "--to-version is not supported together with --file")
 	}
 	return nil
 }
@@ -109,10 +109,10 @@ func validateMarkdownDiffSpec(runtime *common.RuntimeContext, spec markdownDiffS
 func validateMarkdownDiffVersionValue(value, flagName string) error {
 	value = strings.TrimSpace(value)
 	if value == "" {
-		return output.ErrValidation("%s cannot be empty", flagName)
+		return markdownValidationParamError(flagName, "%s cannot be empty", flagName)
 	}
 	if !markdownDiffVersionRe.MatchString(value) {
-		return output.ErrValidation("%s must be a numeric version string", flagName)
+		return markdownValidationParamError(flagName, "%s must be a numeric version string", flagName)
 	}
 	return nil
 }
@@ -178,17 +178,16 @@ func downloadMarkdownContent(ctx context.Context, runtime *common.RuntimeContext
 func readMarkdownLocalFile(runtime *common.RuntimeContext, filePath string) (string, error) {
 	f, err := runtime.FileIO().Open(filePath)
 	if err != nil {
-		return "", common.WrapInputStatError(err)
+		return "", common.WrapInputStatErrorTyped(err)
 	}
 	defer f.Close()
 
 	payload, err := readMarkdownDiffPayload(f, "local Markdown file")
 	if err != nil {
-		var exitErr *output.ExitError
-		if errors.As(err, &exitErr) {
+		if _, ok := errs.ProblemOf(err); ok {
 			return "", err
 		}
-		return "", output.ErrValidation("cannot read file: %s", err)
+		return "", markdownValidationError("cannot read file: %s", err).WithCause(err)
 	}
 	return string(payload), nil
 }
@@ -199,7 +198,7 @@ func readMarkdownDiffPayload(r io.Reader, source string) ([]byte, error) {
 		return nil, err
 	}
 	if len(payload) > markdownDiffMaxContentBytes {
-		return nil, output.ErrValidation("%s exceeds %s markdown +diff content limit", source, common.FormatSize(markdownDiffMaxContentBytes))
+		return nil, markdownValidationError("%s exceeds %s markdown +diff content limit", source, common.FormatSize(markdownDiffMaxContentBytes))
 	}
 	return payload, nil
 }

shortcuts/markdown/markdown_diff_test.go

@@ -13,6 +13,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
@@ -214,18 +215,18 @@ func TestMarkdownDiffRejectsOversizedLocalContent(t *testing.T) {
 }
 
 func TestMarkdownDownloadErrorPreservesStructuredErrors(t *testing.T) {
-	apiErr := output.ErrAPI(99991663, "permission denied", map[string]interface{}{"permission": "drive:file:download"})
+	apiErr := errs.NewAPIError(errs.SubtypePermissionDenied, "permission denied").WithCode(99991663)
 	if got := wrapMarkdownDownloadError(apiErr); got != apiErr {
 		t.Fatalf("wrapMarkdownDownloadError() = %v, want original API error", got)
 	}
 
 	got := wrapMarkdownDownloadError(errors.New("dial tcp timeout"))
-	var exitErr *output.ExitError
-	if !errors.As(got, &exitErr) {
-		t.Fatalf("wrapMarkdownDownloadError() = %T, want *output.ExitError", got)
+	problem, ok := errs.ProblemOf(got)
+	if !ok {
+		t.Fatalf("wrapMarkdownDownloadError() = %T, want typed problem", got)
 	}
-	if exitErr.Code != output.ExitNetwork {
-		t.Fatalf("exit code = %d, want %d", exitErr.Code, output.ExitNetwork)
+	if problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("problem = %s/%s, want %s/%s", problem.Category, problem.Subtype, errs.CategoryNetwork, errs.SubtypeNetworkTransport)
 	}
 	if !strings.Contains(got.Error(), "download failed: dial tcp timeout") {
 		t.Fatalf("wrapped error = %q", got.Error())

shortcuts/markdown/markdown_errors.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package markdown
+
+import (
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func markdownValidationError(format string, args ...any) *errs.ValidationError {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func markdownValidationParamError(param, format string, args ...any) *errs.ValidationError {
+	return markdownValidationError(format, args...).WithParam(param)
+}
+
+func markdownInvalidParam(name, reason string) errs.InvalidParam {
+	return errs.InvalidParam{Name: name, Reason: reason}
+}
+
+func markdownNetworkError(err error, format string, args ...any) error {
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
+	return errs.NewNetworkError(errs.SubtypeNetworkTransport, format, args...).WithCause(err)
+}
+
+func wrapMarkdownDownloadError(err error) error {
+	if p, ok := errs.ProblemOf(err); ok {
+		if p.Category == errs.CategoryValidation {
+			return err
+		}
+		return markdownPrefixProblem(err, "download failed")
+	}
+	return markdownNetworkError(err, "download failed: %s", err)
+}
+
+func markdownPrefixProblem(err error, action string) error {
+	if p, ok := errs.ProblemOf(err); ok {
+		if strings.TrimSpace(action) != "" {
+			p.Message = action + ": " + p.Message
+		}
+		return err
+	}
+	return errs.WrapInternal(err)
+}

shortcuts/markdown/markdown_fetch.go

@@ -14,7 +14,6 @@ import (
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -35,14 +34,14 @@ var MarkdownFetch = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		fileToken := strings.TrimSpace(runtime.Str("file-token"))
 		if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--file-token", "%s", err).WithCause(err)
 		}
 		outputPath := strings.TrimSpace(runtime.Str("output"))
 		if outputPath == "" {
 			return nil
 		}
 		if _, err := validate.SafeOutputPath(outputPath); err != nil {
-			return output.ErrValidation("unsafe output path: %s", err)
+			return markdownValidationParamError("--output", "unsafe output path: %s", err).WithCause(err)
 		}
 		return nil
 	},
@@ -67,7 +66,7 @@ var MarkdownFetch = common.Shortcut{
 			ApiPath:    fmt.Sprintf("/open-apis/drive/v1/files/%s/download", validate.EncodePathSegment(fileToken)),
 		})
 		if err != nil {
-			return output.ErrNetwork("download failed: %s", err)
+			return wrapMarkdownDownloadError(err)
 		}
 		defer resp.Body.Close()
 
@@ -75,7 +74,7 @@ var MarkdownFetch = common.Shortcut{
 		if outputPath == "" {
 			payload, err := io.ReadAll(resp.Body)
 			if err != nil {
-				return output.ErrNetwork("download failed: %s", err)
+				return wrapMarkdownDownloadError(err)
 			}
 			out := map[string]interface{}{
 				"file_token": fileToken,
@@ -93,7 +92,7 @@ var MarkdownFetch = common.Shortcut{
 			outputPath = filepath.Join(outputPath, fileName)
 		}
 		if _, statErr := runtime.FileIO().Stat(outputPath); statErr == nil && !runtime.Bool("overwrite") {
-			return output.ErrValidation("output file already exists: %s (use --overwrite to replace)", outputPath)
+			return markdownValidationParamError("--output", "output file already exists: %s (use --overwrite to replace)", outputPath)
 		}
 
 		result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
@@ -101,7 +100,7 @@ var MarkdownFetch = common.Shortcut{
 			ContentLength: resp.ContentLength,
 		}, resp.Body)
 		if err != nil {
-			return common.WrapSaveErrorByCategory(err, "io")
+			return common.WrapSaveErrorTyped(err)
 		}
 
 		savedPath, _ := runtime.ResolveSavePath(outputPath)

shortcuts/markdown/markdown_overwrite.go

@@ -8,7 +8,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -30,7 +29,7 @@ var MarkdownOverwrite = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		fileToken := strings.TrimSpace(runtime.Str("file-token"))
 		if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return markdownValidationParamError("--file-token", "%s", err).WithCause(err)
 		}
 		return validateMarkdownSpec(runtime, markdownUploadSpec{
 			FileToken:  fileToken,

shortcuts/markdown/markdown_patch.go

@@ -10,7 +10,6 @@ import (
 	"regexp"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -49,7 +48,7 @@ var MarkdownPatch = common.Shortcut{
 		}
 		if spec.Regex {
 			if _, err := regexp.Compile(spec.Pattern); err != nil {
-				return output.ErrValidation("invalid --pattern regex: %s", err)
+				return markdownValidationParamError("--pattern", "invalid --pattern regex: %s", err).WithCause(err)
 			}
 		}
 		return nil
@@ -122,7 +121,7 @@ var MarkdownPatch = common.Shortcut{
 
 		payload, err := io.ReadAll(resp.Body)
 		if err != nil {
-			return output.ErrNetwork("download failed: %s", err)
+			return wrapMarkdownDownloadError(err)
 		}
 		original := string(payload)
 		patched, matchCount, err := applyMarkdownPatch(original, spec)
@@ -192,16 +191,16 @@ func newMarkdownPatchSpec(runtime *common.RuntimeContext) markdownPatchSpec {
 
 func validateMarkdownPatchSpec(runtime *common.RuntimeContext, spec markdownPatchSpec) error {
 	if err := validate.ResourceName(spec.FileToken, "--file-token"); err != nil {
-		return output.ErrValidation("%s", err)
+		return markdownValidationParamError("--file-token", "%s", err).WithCause(err)
 	}
 	if !runtime.Changed("pattern") {
-		return common.FlagErrorf("--pattern is required")
+		return markdownValidationParamError("--pattern", "--pattern is required")
 	}
 	if spec.Pattern == "" {
-		return output.ErrValidation("--pattern cannot be empty")
+		return markdownValidationParamError("--pattern", "--pattern cannot be empty")
 	}
 	if !spec.ContentSet {
-		return common.FlagErrorf("--content is required")
+		return markdownValidationParamError("--content", "--content is required")
 	}
 	return nil
 }
@@ -212,7 +211,7 @@ func applyMarkdownPatch(original string, spec markdownPatchSpec) (string, int, e
 	}
 	re, err := regexp.Compile(spec.Pattern)
 	if err != nil {
-		return "", 0, output.ErrValidation("invalid --pattern regex: %s", err)
+		return "", 0, markdownValidationParamError("--pattern", "invalid --pattern regex: %s", err).WithCause(err)
 	}
 	matches := re.FindAllStringIndex(original, -1)
 	return re.ReplaceAllString(original, spec.Content), len(matches), nil

shortcuts/markdown/markdown_test.go

@@ -17,9 +17,11 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -603,6 +605,100 @@ func TestMarkdownCreateSuccessUploadAllToWikiReturnsMetaURL(t *testing.T) {
 	}
 }
 
+func TestMarkdownCreateUploadAllReturnsTypedScopeError(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "Access denied. One of the following scopes is required: [drive:file:upload]",
+			"error": map[string]interface{}{
+				"log_id": "log-md-upload-scope",
+			},
+		},
+	})
+
+	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
+		"+create",
+		"--name", "README.md",
+		"--content", "# hello\n",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected scope error")
+	}
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Code != 99991672 {
+		t.Fatalf("code = %d, want 99991672", p.Code)
+	}
+	if p.Subtype != errs.SubtypeAppScopeNotApplied {
+		t.Fatalf("subtype = %s, want %s", p.Subtype, errs.SubtypeAppScopeNotApplied)
+	}
+	if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
+		t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadAllAction+": ")
+	}
+	if !strings.Contains(p.Hint, "lacks the required document upload scope") {
+		t.Fatalf("hint = %q, want upload scope guidance", p.Hint)
+	}
+}
+
+func TestMarkdownCreateUploadAllRetriesRateLimit(t *testing.T) {
+	f, stdout, stderr, reg := cmdutil.TestFactory(t, markdownTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 99991400,
+			"msg":  "request frequency limit exceeded",
+			"error": map[string]interface{}{
+				"log_id": "log-md-upload-ratelimit-1",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"file_token": "box_md_retry_success",
+				"version":    "1003",
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"metas": []map[string]interface{}{
+					{"doc_token": "box_md_retry_success", "doc_type": "file", "url": "https://tenant.example.com/file/box_md_retry_success"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunMarkdown(t, MarkdownCreate, []string{
+		"+create",
+		"--name", "README.md",
+		"--content", "# hello\n",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stderr.String(), "retrying (attempt 1/2)") {
+		t.Fatalf("stderr = %q, want retry log", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"file_token": "box_md_retry_success"`) {
+		t.Fatalf("stdout missing retried upload token: %s", stdout.String())
+	}
+}
+
 func TestMarkdownCreatePrettyOutputIncludesPermissionGrant(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
@@ -1033,6 +1129,270 @@ func TestUploadMarkdownMultipartPartsRejectsOversizedBlockSize(t *testing.T) {
 	}
 }
 
+func TestWithMarkdownUploadRetryDataDoesNotRetryNonRetryable(t *testing.T) {
+	f, _, stderr, _ := cmdutil.TestFactory(t, markdownTestConfig())
+	rt := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser)
+
+	attempts := 0
+	expected := errs.NewAPIError(errs.SubtypePermissionDenied, "permission denied").WithCode(1061004)
+	_, err := withMarkdownUploadRetryData(rt, markdownUploadAllAction, func() (map[string]interface{}, error) {
+		attempts++
+		return nil, expected
+	})
+	if err != expected {
+		t.Fatalf("err = %v, want original error", err)
+	}
+	if attempts != 1 {
+		t.Fatalf("attempts = %d, want 1", attempts)
+	}
+	if stderr.String() != "" {
+		t.Fatalf("stderr = %q, want no retry log", stderr.String())
+	}
+}
+
+func TestWithMarkdownUploadRetryVoidExhaustedAppendsHint(t *testing.T) {
+	f, _, stderr, _ := cmdutil.TestFactory(t, markdownTestConfig())
+	rt := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser)
+
+	orig := markdownUploadRetryBackoffs
+	markdownUploadRetryBackoffs = []time.Duration{0, 0}
+	t.Cleanup(func() { markdownUploadRetryBackoffs = orig })
+
+	attempts := 0
+	err := withMarkdownUploadRetryVoid(rt, markdownUploadFinishAction, func() error {
+		attempts++
+		return errs.NewAPIError(errs.SubtypeRateLimit, "too many requests").WithCode(99991400).WithRetryable()
+	})
+	if err == nil {
+		t.Fatal("expected retryable error")
+	}
+	if attempts != 3 {
+		t.Fatalf("attempts = %d, want 3", attempts)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if !strings.Contains(p.Hint, "remained retryable after 3 attempts") {
+		t.Fatalf("hint = %q, want retry exhaustion guidance", p.Hint)
+	}
+	if strings.Count(stderr.String(), "retrying (attempt") != 2 {
+		t.Fatalf("stderr = %q, want 2 retry logs", stderr.String())
+	}
+}
+
+func TestMarkdownUploadShouldRetryBranches(t *testing.T) {
+	if markdownUploadShouldRetry(errors.New("plain")) {
+		t.Fatal("plain error should not be retryable")
+	}
+	if !markdownUploadShouldRetry(errs.NewAPIError(errs.SubtypeRateLimit, "slow down").WithRetryable()) {
+		t.Fatal("retryable API error should be retryable")
+	}
+	if !markdownUploadShouldRetry(errs.NewNetworkError(errs.SubtypeNetworkServer, "gateway").WithCode(502)) {
+		t.Fatal("network error should be retryable by category")
+	}
+}
+
+func TestMarkdownUploadRetryExhaustedZeroRetriesKeepsOriginal(t *testing.T) {
+	original := errs.NewAPIError(errs.SubtypeRateLimit, "slow down").WithRetryable()
+	got := markdownUploadRetryExhausted(original, markdownUploadAllAction, 0)
+	if got != original {
+		t.Fatalf("got = %v, want original error", got)
+	}
+}
+
+func TestMarkdownUploadProblemAppendsCodeSpecificHints(t *testing.T) {
+	tests := []struct {
+		name string
+		code int
+		want string
+	}{
+		{
+			name: "missing scope",
+			code: 99991672,
+			want: "lacks the required document upload scope",
+		},
+		{
+			name: "version limit",
+			code: 10071,
+			want: "reached its version limit",
+		},
+		{
+			name: "document capability",
+			code: 90003087,
+			want: "document capabilities enabled",
+		},
+		{
+			name: "target not found",
+			code: 1061044,
+			want: "target folder or wiki node still exists",
+		},
+		{
+			name: "no write access",
+			code: 1062501,
+			want: "has write access",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithCode(tt.code)
+			got := markdownUploadProblem(err, markdownUploadAllAction)
+			p, ok := errs.ProblemOf(got)
+			if !ok {
+				t.Fatalf("expected typed problem, got %T (%v)", got, got)
+			}
+			if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
+				t.Fatalf("message = %q, want action prefix", p.Message)
+			}
+			if !strings.Contains(p.Hint, tt.want) {
+				t.Fatalf("hint = %q, want substring %q", p.Hint, tt.want)
+			}
+		})
+	}
+}
+
+func TestUploadMarkdownFileAllMissingFileTokenGetsActionPrefix(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"version": "1001",
+			},
+		},
+	})
+
+	_, err := uploadMarkdownFileAll(
+		common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
+		markdownUploadSpec{ContentSet: true},
+		"README.md",
+		int64(len("# hello\n")),
+		func() (io.ReadCloser, error) {
+			return io.NopCloser(strings.NewReader("# hello\n")), nil
+		},
+	)
+	if err == nil {
+		t.Fatal("expected parse error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if !strings.HasPrefix(p.Message, markdownUploadAllAction+": ") {
+		t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadAllAction+": ")
+	}
+}
+
+func TestUploadMarkdownFileMultipartPrepareAndFinishParseErrorsGetActionPrefix(t *testing.T) {
+	t.Run("prepare", func(t *testing.T) {
+		f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/files/upload_prepare",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"upload_id": "upload_123",
+					"block_num": 1,
+				},
+			},
+		})
+
+		_, err := uploadMarkdownFileMultipart(
+			common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
+			markdownUploadSpec{ContentSet: true},
+			"README.md",
+			int64(len("# hello\n")),
+			func() (io.ReadCloser, error) {
+				return io.NopCloser(strings.NewReader("# hello\n")), nil
+			},
+		)
+		if err == nil {
+			t.Fatal("expected prepare parse error")
+		}
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T (%v)", err, err)
+		}
+		if !strings.HasPrefix(p.Message, markdownUploadPrepareAction+": ") {
+			t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadPrepareAction+": ")
+		}
+	})
+
+	t.Run("finish", func(t *testing.T) {
+		f, _, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/files/upload_prepare",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"upload_id":  "upload_123",
+					"block_size": float64(8),
+					"block_num":  float64(1),
+				},
+			},
+		})
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/files/upload_part",
+			Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+		})
+		reg.Register(&httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/drive/v1/files/upload_finish",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"version": "1001",
+				},
+			},
+		})
+
+		_, err := uploadMarkdownFileMultipart(
+			common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "+create"}, markdownTestConfig(), f, core.AsUser),
+			markdownUploadSpec{ContentSet: true},
+			"README.md",
+			int64(len("# hello\n")),
+			func() (io.ReadCloser, error) {
+				return io.NopCloser(strings.NewReader("# hello\n")), nil
+			},
+		)
+		if err == nil {
+			t.Fatal("expected finish parse error")
+		}
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T (%v)", err, err)
+		}
+		if !strings.HasPrefix(p.Message, markdownUploadFinishAction+": ") {
+			t.Fatalf("message = %q, want %q prefix", p.Message, markdownUploadFinishAction+": ")
+		}
+	})
+}
+
+func TestAppendMarkdownProblemHintAppendsAndIgnoresBlank(t *testing.T) {
+	err := errs.NewAPIError(errs.SubtypeUnknown, "boom").WithHint("first")
+	appendMarkdownProblemHint(err, "second")
+	appendMarkdownProblemHint(err, "   ")
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Hint != "first\nsecond" {
+		t.Fatalf("hint = %q, want newline-joined hints", p.Hint)
+	}
+
+	plain := errors.New("plain")
+	if got := appendMarkdownProblemHint(plain, "ignored"); got != plain {
+		t.Fatalf("plain error should pass through unchanged")
+	}
+}
+
 func TestMarkdownOverwriteUploadAllIncludesFileTokenAndVersion(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
 	reg.Register(&httpmock.Stub{
@@ -1303,7 +1663,18 @@ func TestMarkdownOverwriteRejectsEmptyLocalFile(t *testing.T) {
 }
 
 func TestMarkdownOverwriteMetadataLookupFailure(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, markdownTestConfig())
+	f, stdout, _, reg := cmdutil.TestFactory(t, markdownTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/metas/batch_query",
+		Body: map[string]interface{}{
+			"code": 1061044,
+			"msg":  "parent node not exist",
+			"error": map[string]interface{}{
+				"log_id": "log-md-meta-notfound",
+			},
+		},
+	})
 
 	err := mountAndRunMarkdown(t, MarkdownOverwrite, []string{
 		"+overwrite",
@@ -1313,6 +1684,19 @@ func TestMarkdownOverwriteMetadataLookupFailure(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected metadata lookup failure")
 	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T (%v)", err, err)
+	}
+	if p.Code != 1061044 {
+		t.Fatalf("code = %d, want 1061044", p.Code)
+	}
+	if !strings.HasPrefix(p.Message, markdownFetchNameAction+": ") {
+		t.Fatalf("message = %q, want %q prefix", p.Message, markdownFetchNameAction+": ")
+	}
+	if !strings.Contains(p.Hint, "target folder or wiki node still exists") {
+		t.Fatalf("hint = %q, want target guidance", p.Hint)
+	}
 }
 
 func TestMarkdownOverwriteMissingFileReturnsReadError(t *testing.T) {

shortcuts/minutes/minutes_download.go

@@ -17,6 +17,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -54,29 +55,29 @@ var MinutesDownload = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
 		if len(tokens) == 0 {
-			return output.ErrValidation("--minute-tokens is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens is required").WithParam("--minute-tokens")
 		}
 		if len(tokens) > maxBatchSize {
-			return output.ErrValidation("--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize).WithParam("--minute-tokens")
 		}
 		for _, token := range tokens {
 			if !validMinuteToken.MatchString(token) {
-				return output.ErrValidation("invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token).WithParam("--minute-tokens")
 			}
 		}
 		// Cheap checks first, then path-safety resolution.
 		out := runtime.Str("output")
 		outDir := runtime.Str("output-dir")
 		if out != "" && outDir != "" {
-			return output.ErrValidation("--output and --output-dir cannot both be set")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --output-dir cannot both be set").WithParam("--output")
 		}
 		if out != "" {
-			if err := common.ValidateSafePath(runtime.FileIO(), out); err != nil {
+			if err := common.ValidateSafePathTyped(runtime.FileIO(), out); err != nil {
 				return err
 			}
 		}
 		if outDir != "" {
-			if err := common.ValidateSafePath(runtime.FileIO(), outDir); err != nil {
+			if err := common.ValidateSafePathTyped(runtime.FileIO(), outDir); err != nil {
 				return err
 			}
 		}
@@ -112,7 +113,7 @@ var MinutesDownload = common.Shortcut{
 				explicitOutputPath = ""
 			case statErr == nil && !fi.IsDir():
 				if !single {
-					return output.ErrValidation("--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath)
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath).WithParam("--output")
 				}
 			case errors.Is(statErr, fs.ErrNotExist):
 				if !single {
@@ -120,7 +121,7 @@ var MinutesDownload = common.Shortcut{
 					explicitOutputPath = ""
 				}
 			default:
-				return output.Errorf(output.ExitAPI, "io_error", "cannot access --output %q: %s", explicitOutputPath, statErr)
+				return errs.NewInternalError(errs.SubtypeFileIO, "cannot access --output %q: %s", explicitOutputPath, statErr).WithCause(statErr)
 			}
 		}
 
@@ -137,6 +138,7 @@ var MinutesDownload = common.Shortcut{
 			SizeBytes    int64  `json:"size_bytes,omitempty"`
 			DownloadURL  string `json:"download_url,omitempty"`
 			Error        string `json:"error,omitempty"`
+			err          error  // raw typed error for single-mode passthrough
 		}
 
 		results := make([]result, len(tokens))
@@ -151,18 +153,18 @@ var MinutesDownload = common.Shortcut{
 		// download URLs originate from the trusted Lark API, not user input.
 		baseClient, err := runtime.Factory.HttpClient()
 		if err != nil {
-			return output.ErrNetwork("failed to get HTTP client: %s", err)
+			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "failed to get HTTP client: %s", err).WithCause(err)
 		}
 		clonedClient := *baseClient
 		clonedClient.Timeout = disableClientTimeout
 		clonedClient.CheckRedirect = func(req *http.Request, via []*http.Request) error {
 			if len(via) >= maxDownloadRedirects {
-				return fmt.Errorf("too many redirects")
+				return fmt.Errorf("too many redirects") //nolint:forbidigo // returned to net/http CheckRedirect, not a CLI terminal error
 			}
 			if len(via) > 0 {
 				prev := via[len(via)-1]
 				if strings.EqualFold(prev.URL.Scheme, "https") && strings.EqualFold(req.URL.Scheme, "http") {
-					return fmt.Errorf("redirect from https to http is not allowed")
+					return fmt.Errorf("redirect from https to http is not allowed") //nolint:forbidigo // returned to net/http CheckRedirect, not a CLI terminal error
 				}
 			}
 			return validate.ValidateDownloadSourceURL(req.Context(), req.URL.String())
@@ -193,7 +195,7 @@ var MinutesDownload = common.Shortcut{
 
 			downloadURL, err := fetchDownloadURL(ctx, runtime, token)
 			if err != nil {
-				results[i] = result{MinuteToken: token, Error: err.Error()}
+				results[i] = result{MinuteToken: token, Error: err.Error(), err: err}
 				continue
 			}
 
@@ -220,7 +222,7 @@ var MinutesDownload = common.Shortcut{
 
 			dl, err := downloadMediaFile(ctx, dlClient, downloadURL, token, opts)
 			if err != nil {
-				results[i] = result{MinuteToken: token, Error: err.Error()}
+				results[i] = result{MinuteToken: token, Error: err.Error(), err: err}
 				continue
 			}
 			results[i] = result{
@@ -235,7 +237,10 @@ var MinutesDownload = common.Shortcut{
 		if single {
 			r := results[0]
 			if r.Error != "" {
-				return output.ErrAPI(0, r.Error, nil)
+				if r.err != nil {
+					return r.err // typed error from fetchDownloadURL/downloadMediaFile, exit code preserved
+				}
+				return runtime.OutPartialFailure(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)})
 			}
 			if urlOnly {
 				runtime.Out(map[string]interface{}{
@@ -262,17 +267,19 @@ var MinutesDownload = common.Shortcut{
 		}
 		fmt.Fprintf(errOut, "[minutes +download] done: %d total, %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
 
-		runtime.OutFormat(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)}, nil)
+		outData := map[string]interface{}{"downloads": results}
+		meta := &output.Meta{Count: len(results)}
 		if successCount == 0 && len(results) > 0 {
-			return output.ErrAPI(0, fmt.Sprintf("all %d downloads failed", len(results)), nil)
+			return runtime.OutPartialFailure(outData, meta)
 		}
+		runtime.OutFormat(outData, meta, nil)
 		return nil
 	},
 }
 
 // fetchDownloadURL retrieves the pre-signed download URL for a minute token.
 func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) (string, error) {
-	data, err := runtime.DoAPIJSON(http.MethodGet,
+	data, err := runtime.CallAPITyped(http.MethodGet,
 		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/media", validate.EncodePathSegment(minuteToken)),
 		nil, nil)
 	if err != nil {
@@ -280,7 +287,7 @@ func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minut
 	}
 	downloadURL := common.GetString(data, "download_url")
 	if downloadURL == "" {
-		return "", output.Errorf(output.ExitAPI, "api_error", "API returned empty download_url for %s", minuteToken)
+		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned empty download_url for %s", minuteToken)
 	}
 	return downloadURL, nil
 }
@@ -302,26 +309,26 @@ type downloadOpts struct {
 // Filename resolution: opts.outputPath > Content-Disposition filename > Content-Type ext > <token>.media.
 func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, minuteToken string, opts downloadOpts) (*downloadResult, error) {
 	if err := validate.ValidateDownloadSourceURL(ctx, downloadURL); err != nil {
-		return nil, output.ErrValidation("blocked download URL: %s", err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "blocked download URL: %s", err).WithCause(err)
 	}
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
 	if err != nil {
-		return nil, output.ErrNetwork("invalid download URL: %s", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "invalid download URL: %s", err).WithCause(err)
 	}
 
 	resp, err := client.Do(req)
 	if err != nil {
-		return nil, output.ErrNetwork("download failed: %s", err)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: %s", err).WithCause(err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		if len(body) > 0 {
-			return nil, output.ErrNetwork("download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
 		}
-		return nil, output.ErrNetwork("download failed: HTTP %d", resp.StatusCode)
+		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d", resp.StatusCode)
 	}
 
 	// resolve output path
@@ -340,7 +347,7 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 
 	if !opts.overwrite {
 		if _, statErr := opts.fio.Stat(outputPath); statErr == nil {
-			return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", outputPath)
+			return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", outputPath)
 		}
 	}
 
@@ -349,7 +356,7 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 		ContentLength: resp.ContentLength,
 	}, resp.Body)
 	if err != nil {
-		return nil, common.WrapSaveErrorByCategory(err, "io")
+		return nil, common.WrapSaveErrorTyped(err)
 	}
 	resolvedPath, err := opts.fio.ResolvePath(outputPath)
 	if err != nil || resolvedPath == "" {

shortcuts/minutes/minutes_download_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"os"
 	"strings"
@@ -15,9 +16,11 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -694,3 +697,284 @@ func TestDownload_Batch_DryRun(t *testing.T) {
 		t.Errorf("dry-run should show tokens, got: %s", out)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// Typed-error lock tests
+// ---------------------------------------------------------------------------
+
+// TestDownload_TypedErr_ValidationInvalidArgument verifies that an invalid
+// minute token format (passing cobra's required check but failing our regex)
+// returns a *errs.ValidationError with SubtypeInvalidArgument and the expected
+// Param.  This locks site :64 (invalid minute token %q).
+func TestDownload_TypedErr_ValidationInvalidArgument(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, MinutesDownload, []string{
+		"+download", "--minute-tokens", "INVALID***TOKEN", "--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if ve.Param != "--minute-tokens" {
+		t.Errorf("Param = %q, want %q", ve.Param, "--minute-tokens")
+	}
+}
+
+// TestDownload_TypedErr_NetworkTransport_HttpError verifies that a non-2xx
+// download response from downloadMediaFile returns a *errs.NetworkError with
+// SubtypeNetworkTransport.
+//
+// In the end-to-end single-token Execute path the typed error is now passed
+// through directly via r.err (single-mode passthrough).  We call downloadMediaFile
+// directly via a probe shortcut to assert the typed shape at the source.
+func TestDownload_TypedErr_NetworkTransport_HttpError(t *testing.T) {
+	chdir(t, t.TempDir())
+
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-dl",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			client, err := rctx.Factory.HttpClient()
+			if err != nil {
+				return err
+			}
+			_, capturedErr = downloadMediaFile(ctx, client,
+				"https://example.com/presigned/download", "tok001",
+				downloadOpts{fio: rctx.FileIO(), outputPath: "out.mp4"})
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		URL:     "example.com/presigned/download",
+		Status:  503,
+		RawBody: []byte("Service Unavailable"),
+	})
+
+	if err := mountAndRun(t, probe, []string{"+probe-dl", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected downloadMediaFile to return an error for HTTP 503, got nil")
+	}
+	var ne *errs.NetworkError
+	if !errors.As(capturedErr, &ne) {
+		t.Fatalf("expected *errs.NetworkError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ne.Subtype != errs.SubtypeNetworkTransport {
+		t.Errorf("Subtype = %q, want %q", ne.Subtype, errs.SubtypeNetworkTransport)
+	}
+	if !strings.Contains(ne.Error(), "503") {
+		t.Errorf("error message should contain status code 503, got: %v", ne)
+	}
+}
+
+// TestDownload_TypedErr_InternalInvalidResponse verifies that fetchDownloadURL
+// returns *errs.InternalError with SubtypeInvalidResponse when the API
+// response contains an empty download_url field.
+//
+// In the end-to-end single-token Execute path the typed error is now passed
+// through directly via r.err (single-mode passthrough).  The typed assertion
+// is also made at the fetchDownloadURL call site directly via a probe shortcut.
+func TestDownload_TypedErr_InternalInvalidResponse(t *testing.T) {
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-download-url",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			_, capturedErr = fetchDownloadURL(ctx, rctx, "tok001")
+			// Always return nil so mountAndRun doesn't swallow the error type.
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/tok001/media",
+		Status: 200,
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"download_url": ""},
+		},
+	})
+
+	if err := mountAndRun(t, probe, []string{"+probe-download-url", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected fetchDownloadURL to return an error for empty download_url, got nil")
+	}
+	var ie *errs.InternalError
+	if !errors.As(capturedErr, &ie) {
+		t.Fatalf("expected *errs.InternalError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("Subtype = %q, want %q", ie.Subtype, errs.SubtypeInvalidResponse)
+	}
+	if !strings.Contains(ie.Error(), "download_url") {
+		t.Errorf("error message should mention download_url, got: %v", ie)
+	}
+}
+
+// TestDownload_TypedErr_OverwriteProtection verifies that the overwrite guard
+// in downloadMediaFile returns *errs.ValidationError with SubtypeFailedPrecondition.
+//
+// In the end-to-end single-token Execute path this typed error is now passed
+// through directly via r.err (single-mode passthrough), so the typed shape is
+// also asserted end-to-end via the probe shortcut.
+func TestDownload_TypedErr_OverwriteProtection(t *testing.T) {
+	chdir(t, t.TempDir())
+	if err := os.WriteFile("existing.mp4", []byte("old"), 0644); err != nil {
+		t.Fatalf("setup failed: %v", err)
+	}
+
+	var capturedErr error
+	probe := common.Shortcut{
+		Service:   "minutes",
+		Command:   "+probe-overwrite",
+		AuthTypes: []string{"bot"},
+		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+			client, err := rctx.Factory.HttpClient()
+			if err != nil {
+				return err
+			}
+			_, capturedErr = downloadMediaFile(ctx, client,
+				"https://example.com/presigned/download", "tok001",
+				downloadOpts{fio: rctx.FileIO(), outputPath: "existing.mp4", overwrite: false})
+			return nil
+		},
+	}
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(downloadStub("example.com/presigned/download", []byte("new-content"), "video/mp4"))
+
+	if err := mountAndRun(t, probe, []string{"+probe-overwrite", "--as", "bot"}, f, nil); err != nil {
+		t.Fatalf("probe shortcut should not error: %v", err)
+	}
+	if capturedErr == nil {
+		t.Fatal("expected downloadMediaFile to return an error for existing file without overwrite, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(capturedErr, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", capturedErr, capturedErr)
+	}
+	if ve.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeFailedPrecondition)
+	}
+	if !strings.Contains(ve.Error(), "exists") {
+		t.Errorf("error message should mention exists, got: %v", ve)
+	}
+}
+
+// TestDownload_TypedErr_SingleMode_PassthroughTyped verifies that in single-token
+// mode a typed error from fetchDownloadURL or downloadMediaFile is returned
+// directly to the caller with its Problem shape intact (exit code preserved).
+func TestDownload_TypedErr_SingleMode_PassthroughTyped(t *testing.T) {
+	chdir(t, t.TempDir())
+
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// API returns non-zero code → CallAPITyped yields a typed APIError.
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/tok001/media",
+		Status: 200,
+		Body: map[string]interface{}{
+			"code": 99991, "msg": "permission denied",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, MinutesDownload, []string{
+		"+download", "--minute-tokens", "tok001", "--output", "out.mp4", "--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error for API failure, got nil")
+	}
+
+	// The error must carry a Problem (typed envelope).
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error (ProblemOf ok), got %T: %v", err, err)
+	}
+	if p == nil {
+		t.Fatal("ProblemOf returned nil Problem")
+	}
+
+	// Exit code must be non-zero and come from the typed error, not a generic 1.
+	code := output.ExitCodeOf(err)
+	if code == 0 {
+		t.Errorf("ExitCodeOf typed error = 0, want non-zero")
+	}
+}
+
+// TestDownload_TypedErr_Batch_AllFail_OutPartialFailure verifies that when every
+// token in a batch fails, Execute emits an ok:false stdout envelope (carrying the
+// full downloads array) and returns *output.PartialFailureError with Code==ExitAPI.
+// This locks the double-emit fix: the old code called OutFormat then returned ErrAPI;
+// the new code calls OutPartialFailure once.
+func TestDownload_TypedErr_Batch_AllFail_OutPartialFailure(t *testing.T) {
+	chdir(t, t.TempDir())
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// Both tokens fail at the API level.
+	for _, tok := range []string{"tok001", "tok002"} {
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/minutes/v1/minutes/" + tok + "/media",
+			Status: 200,
+			Body: map[string]interface{}{
+				"code": 99991, "msg": "permission denied",
+				"data": map[string]interface{}{},
+			},
+		})
+	}
+
+	err := mountAndRun(t, MinutesDownload, []string{
+		"+download", "--minute-tokens", "tok001,tok002", "--as", "bot",
+	}, f, stdout)
+
+	// Must return *output.PartialFailureError with ExitAPI.
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	if pfErr.Code != output.ExitAPI {
+		t.Errorf("PartialFailureError.Code = %d, want %d (ExitAPI)", pfErr.Code, output.ExitAPI)
+	}
+
+	// stdout must carry ok:false with the downloads array (both failed entries).
+	var env struct {
+		OK   bool `json:"ok"`
+		Data struct {
+			Downloads []struct {
+				MinuteToken string `json:"minute_token"`
+				Error       string `json:"error"`
+			} `json:"downloads"`
+		} `json:"data"`
+	}
+	if jsonErr := json.Unmarshal(stdout.Bytes(), &env); jsonErr != nil {
+		t.Fatalf("failed to parse stdout: %v\nraw: %s", jsonErr, stdout.String())
+	}
+	if env.OK {
+		t.Errorf("ok must be false on all-fail batch, got ok:true\nstdout: %s", stdout.String())
+	}
+	if len(env.Data.Downloads) != 2 {
+		t.Fatalf("expected 2 download entries, got %d\nstdout: %s", len(env.Data.Downloads), stdout.String())
+	}
+	for _, d := range env.Data.Downloads {
+		if d.Error == "" {
+			t.Errorf("token %s: expected non-empty error field in all-fail batch", d.MinuteToken)
+		}
+	}
+}

shortcuts/minutes/minutes_search.go

@@ -13,6 +13,7 @@ import (
 	"time"
 	"unicode/utf8"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -35,28 +36,28 @@ func parseTimeRange(runtime *common.RuntimeContext) (string, string, error) {
 	if start != "" {
 		parsed, err := toRFC3339(start)
 		if err != nil {
-			return "", "", output.ErrValidation("--start: %v", err)
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
 		}
 		startTime = parsed
 	}
 	if end != "" {
 		parsed, err := toRFC3339(end, "end")
 		if err != nil {
-			return "", "", output.ErrValidation("--end: %v", err)
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
 		endTime = parsed
 	}
 	if startTime != "" && endTime != "" {
 		st, err := time.Parse(time.RFC3339, startTime)
 		if err != nil {
-			return "", "", fmt.Errorf("parse normalized --start: %w", err)
+			return "", "", errs.NewInternalError(errs.SubtypeUnknown, "parse normalized --start: %v", err).WithCause(err)
 		}
 		et, err := time.Parse(time.RFC3339, endTime)
 		if err != nil {
-			return "", "", fmt.Errorf("parse normalized --end: %w", err)
+			return "", "", errs.NewInternalError(errs.SubtypeUnknown, "parse normalized --end: %v", err).WithCause(err)
 		}
 		if st.After(et) {
-			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start (%s) is after --end (%s)", start, end).WithParam("--start")
 		}
 	}
 	return startTime, endTime, nil
@@ -70,7 +71,7 @@ func toRFC3339(input string, hint ...string) (string, error) {
 	}
 	sec, err := strconv.ParseInt(ts, 10, 64)
 	if err != nil {
-		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err) //nolint:forbidigo // intermediate parse error; callers wrap it into a typed ValidationError
 	}
 	return time.Unix(sec, 0).Format(time.RFC3339), nil
 }
@@ -94,7 +95,7 @@ func buildTimeFilter(startTime, endTime string) map[string]interface{} {
 func buildMinutesSearchFilter(runtime *common.RuntimeContext, startTime, endTime string) (map[string]interface{}, error) {
 	filter := map[string]interface{}{}
 
-	ownerIDs, err := common.ResolveOpenIDs("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
+	ownerIDs, err := common.ResolveOpenIDsTyped("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
 	if err != nil {
 		return nil, err
 	}
@@ -102,7 +103,7 @@ func buildMinutesSearchFilter(runtime *common.RuntimeContext, startTime, endTime
 		filter["owner_ids"] = ownerIDs
 	}
 
-	participantIDs, err := common.ResolveOpenIDs("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
+	participantIDs, err := common.ResolveOpenIDsTyped("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
 	if err != nil {
 		return nil, err
 	}
@@ -231,26 +232,26 @@ var MinutesSearch = common.Shortcut{
 			return err
 		}
 		if q := strings.TrimSpace(runtime.Str("query")); q != "" && utf8.RuneCountInString(q) > maxMinutesSearchQueryLen {
-			return output.ErrValidation("--query: length must be between 1 and 50 characters")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--query: length must be between 1 and 50 characters").WithParam("--query")
 		}
-		if _, err := common.ValidatePageSize(runtime, "page-size", defaultMinutesSearchPageSize, 1, maxMinutesSearchPageSize); err != nil {
+		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", defaultMinutesSearchPageSize, 1, maxMinutesSearchPageSize); err != nil {
 			return err
 		}
-		ownerIDs, err := common.ResolveOpenIDs("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
+		ownerIDs, err := common.ResolveOpenIDsTyped("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
 		if err != nil {
 			return err
 		}
 		for _, id := range ownerIDs {
-			if _, err := common.ValidateUserID(id); err != nil {
+			if _, err := common.ValidateUserIDTyped("--owner-ids", id); err != nil {
 				return err
 			}
 		}
-		participantIDs, err := common.ResolveOpenIDs("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
+		participantIDs, err := common.ResolveOpenIDsTyped("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
 		if err != nil {
 			return err
 		}
 		for _, id := range participantIDs {
-			if _, err := common.ValidateUserID(id); err != nil {
+			if _, err := common.ValidateUserIDTyped("--participant-ids", id); err != nil {
 				return err
 			}
 		}
@@ -259,7 +260,7 @@ var MinutesSearch = common.Shortcut{
 				return nil
 			}
 		}
-		return common.FlagErrorf("specify at least one of --query, --owner-ids, --participant-ids, --start, or --end")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --query, --owner-ids, --participant-ids, --start, or --end")
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		startTime, endTime, err := parseTimeRange(runtime)
@@ -288,7 +289,7 @@ var MinutesSearch = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPI(http.MethodPost, "/open-apis/minutes/v1/minutes/search", buildMinutesSearchParams(runtime), body)
+		data, err := runtime.CallAPITyped(http.MethodPost, "/open-apis/minutes/v1/minutes/search", buildMinutesSearchParams(runtime), body)
 		if err != nil {
 			return err
 		}

shortcuts/minutes/minutes_search_test.go

@@ -6,9 +6,11 @@ package minutes
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -63,10 +65,11 @@ func TestMinutesSearchParseTimeRangeErrors(t *testing.T) {
 		start       string
 		end         string
 		wantMessage string
+		wantParam   string
 	}{
-		{name: "invalid start", start: "bad-start", wantMessage: "--start:"},
-		{name: "invalid end", end: "bad-end", wantMessage: "--end:"},
-		{name: "start after end", start: "2026-03-26", end: "2026-03-25", wantMessage: "is after --end"},
+		{name: "invalid start", start: "bad-start", wantMessage: "--start:", wantParam: "--start"},
+		{name: "invalid end", end: "bad-end", wantMessage: "--end:", wantParam: "--end"},
+		{name: "start after end", start: "2026-03-26", end: "2026-03-25", wantMessage: "is after --end", wantParam: "--start"},
 	}
 
 	for _, tt := range tests {
@@ -88,6 +91,16 @@ func TestMinutesSearchParseTimeRangeErrors(t *testing.T) {
 			if !strings.Contains(err.Error(), tt.wantMessage) {
 				t.Fatalf("error = %v, want %q", err, tt.wantMessage)
 			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("expected *errs.ValidationError, got %T", err)
+			}
+			if ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+			}
+			if ve.Param != tt.wantParam {
+				t.Fatalf("Param = %q, want %q", ve.Param, tt.wantParam)
+			}
 		})
 	}
 }
@@ -209,6 +222,16 @@ func TestMinutesSearchValidationMeRequiresResolvableUser(t *testing.T) {
 			if !strings.Contains(err.Error(), "resolvable open_id") {
 				t.Fatalf("unexpected error: %v", err)
 			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("expected *errs.ValidationError, got %T", err)
+			}
+			if ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+			}
+			if ve.Param != "--"+tt.flag {
+				t.Fatalf("Param = %q, want --%s", ve.Param, tt.flag)
+			}
 		})
 	}
 }
@@ -267,6 +290,13 @@ func TestMinutesSearchValidationNoFilter(t *testing.T) {
 	if !strings.Contains(err.Error(), "specify at least one") {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
 }
 
 // TestMinutesSearchValidationInvalidParticipantID verifies participant IDs must be valid open_ids.
@@ -279,6 +309,16 @@ func TestMinutesSearchValidationInvalidParticipantID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected invalid user ID error")
 	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+	if ve.Param != "--participant-ids" {
+		t.Fatalf("Param = %q, want --participant-ids", ve.Param)
+	}
 }
 
 // TestMinutesSearchValidationInvalidOwnerID verifies owner IDs must be valid open_ids.
@@ -291,6 +331,16 @@ func TestMinutesSearchValidationInvalidOwnerID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected invalid owner ID error")
 	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+	if ve.Param != "--owner-ids" {
+		t.Fatalf("Param = %q, want --owner-ids", ve.Param)
+	}
 }
 
 // TestMinutesSearchValidationQueryTooLong verifies overly long queries are rejected.
@@ -306,6 +356,16 @@ func TestMinutesSearchValidationQueryTooLong(t *testing.T) {
 	if !strings.Contains(err.Error(), "length must be between 1 and 50 characters") {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+	if ve.Param != "--query" {
+		t.Fatalf("Param = %q, want --query", ve.Param)
+	}
 }
 
 // TestMinutesSearchValidationMaxPageSize30 verifies the maximum allowed page size passes validation.
@@ -335,6 +395,16 @@ func TestMinutesSearchValidationPageSizeAboveMax(t *testing.T) {
 	if !strings.Contains(err.Error(), "--page-size") {
 		t.Fatalf("unexpected error: %v", err)
 	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+	if ve.Param != "--page-size" {
+		t.Fatalf("Param = %q, want --page-size", ve.Param)
+	}
 }
 
 // TestMinutesSearchValidationTimeErrors verifies time parsing failures surface through validation.
@@ -372,6 +442,13 @@ func TestMinutesSearchValidationTimeErrors(t *testing.T) {
 			if !strings.Contains(err.Error(), tt.wantMessage) {
 				t.Fatalf("error = %v, want %q", err, tt.wantMessage)
 			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("expected *errs.ValidationError, got %T", err)
+			}
+			if ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+			}
 		})
 	}
 }

shortcuts/minutes/minutes_speaker_replace.go

@@ -5,12 +5,11 @@ package minutes
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"net/http"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -37,27 +36,27 @@ var MinutesSpeakerReplace = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
 		if minuteToken == "" {
-			return output.ErrValidation("--minute-token is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-token is required").WithParam("--minute-token")
 		}
 		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
 		}
 		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
 		if fromUserID == "" {
-			return output.ErrValidation("--from-user-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id is required").WithParam("--from-user-id")
 		}
-		if _, err := common.ValidateUserID(fromUserID); err != nil {
-			return output.ErrValidation("--from-user-id: %s", err)
+		if _, err := common.ValidateUserIDTyped("--from-user-id", fromUserID); err != nil {
+			return err
 		}
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 		if toUserID == "" {
-			return output.ErrValidation("--to-user-id is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--to-user-id is required").WithParam("--to-user-id")
 		}
-		if _, err := common.ValidateUserID(toUserID); err != nil {
-			return output.ErrValidation("--to-user-id: %s", err)
+		if _, err := common.ValidateUserIDTyped("--to-user-id", toUserID); err != nil {
+			return err
 		}
 		if fromUserID == toUserID {
-			return output.ErrValidation("--from-user-id and --to-user-id must be different")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id and --to-user-id must be different").WithParam("--to-user-id")
 		}
 		return nil
 	},
@@ -84,7 +83,7 @@ var MinutesSpeakerReplace = common.Shortcut{
 			"to_user_id":   toUserID,
 		}
 
-		_, err := runtime.CallAPI(http.MethodPut,
+		_, err := runtime.CallAPITyped(http.MethodPut,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
 			nil, body)
 		if err != nil {
@@ -103,37 +102,18 @@ var MinutesSpeakerReplace = common.Shortcut{
 }
 
 func minutesSpeakerReplaceError(err error, minuteToken, fromUserID string) error {
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
+	p, ok := errs.ProblemOf(err)
+	if !ok {
 		return err
 	}
-
-	switch exitErr.Detail.Code {
+	switch p.Code {
 	case minutesSpeakerReplaceNoEditPermission:
-		return &output.ExitError{
-			Code: output.ExitAPI,
-			Detail: &output.ErrDetail{
-				Type:    "no_edit_permission",
-				Code:    minutesSpeakerReplaceNoEditPermission,
-				Message: fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken),
-				Hint:    "Ask the minute owner for minute edit permission",
-				Detail:  exitErr.Detail.Detail,
-			},
-			Err: err,
-		}
+		p.Message = fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken)
+		p.Hint = "Ask the minute owner for minute edit permission"
 	case minutesSpeakerReplaceSpeakerNotFoundCode:
-		return &output.ExitError{
-			Code: output.ExitAPI,
-			Detail: &output.ErrDetail{
-				Type:    "speaker_not_found",
-				Code:    minutesSpeakerReplaceSpeakerNotFoundCode,
-				Message: fmt.Sprintf("Speaker not found in minute %q: --from-user-id %q does not match an existing speaker in the transcript.", minuteToken, fromUserID),
-				Hint:    "Check --minute-token and --from-user-id. Use an open_id for a speaker that appears in the minute transcript, then retry.",
-				Detail:  exitErr.Detail.Detail,
-			},
-			Err: err,
-		}
+		p.Subtype = errs.SubtypeNotFound
+		p.Message = fmt.Sprintf("Speaker not found in minute %q: --from-user-id %q does not match an existing speaker in the transcript.", minuteToken, fromUserID)
+		p.Hint = "Check --minute-token and --from-user-id. Use an open_id for a speaker that appears in the minute transcript, then retry."
 	}
-
 	return err
 }

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -10,9 +10,9 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -44,12 +44,12 @@ func TestMinutesSpeakerReplace_Validate(t *testing.T) {
 		{
 			name:    "invalid from prefix",
 			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "u_a", "--to-user-id", "ou_b", "--as", "user"},
-			wantErr: "--from-user-id",
+			wantErr: "invalid user ID format",
 		},
 		{
 			name:    "invalid to prefix",
 			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_a", "--to-user-id", "u_b", "--as", "user"},
-			wantErr: "--to-user-id",
+			wantErr: "invalid user ID format",
 		},
 		{
 			name:    "from equals to",
@@ -76,6 +76,52 @@ func TestMinutesSpeakerReplace_Validate(t *testing.T) {
 	}
 }
 
+func TestMinutesSpeakerReplace_ValidateTyped(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	tests := []struct {
+		name      string
+		args      []string
+		wantParam string
+	}{
+		{
+			name:      "invalid from prefix",
+			args:      []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "u_a", "--to-user-id", "ou_b", "--as", "user"},
+			wantParam: "--from-user-id",
+		},
+		{
+			name:      "from equals to",
+			args:      []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_same", "--to-user-id", "ou_same", "--as", "user"},
+			wantParam: "--to-user-id",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			parent := &cobra.Command{Use: "minutes"}
+			MinutesSpeakerReplace.Mount(parent, f)
+			parent.SetArgs(tt.args)
+			parent.SilenceErrors = true
+			parent.SilenceUsage = true
+			err := parent.Execute()
+			if err == nil {
+				t.Fatalf("expected error, got nil")
+			}
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("want *errs.ValidationError, got %T", err)
+			}
+			if ve.Subtype != errs.SubtypeInvalidArgument {
+				t.Errorf("subtype=%q", ve.Subtype)
+			}
+			if ve.Param != tt.wantParam {
+				t.Errorf("param=%q, want %q", ve.Param, tt.wantParam)
+			}
+		})
+	}
+}
+
 func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
@@ -179,24 +225,21 @@ func TestMinutesSpeakerReplace_SpeakerNotFound(t *testing.T) {
 		t.Fatal("expected speaker-not-found error, got nil")
 	}
 
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want typed errs.*, got %T: %v", err, err)
 	}
-	if exitErr.Detail == nil {
-		t.Fatalf("expected structured error detail, got nil")
+	if p.Subtype != errs.SubtypeNotFound {
+		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypeNotFound)
 	}
-	if exitErr.Detail.Type != "speaker_not_found" {
-		t.Errorf("error type = %q, want speaker_not_found", exitErr.Detail.Type)
+	if !strings.Contains(p.Message, "Speaker not found") {
+		t.Errorf("message should be friendly, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "Speaker not found") {
-		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
+	if !strings.Contains(p.Message, "ou_missing_speaker") {
+		t.Errorf("message should include missing speaker id, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "ou_missing_speaker") {
-		t.Errorf("message should include missing speaker id, got: %s", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "--from-user-id") {
-		t.Errorf("hint should mention --from-user-id, got: %s", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "--from-user-id") {
+		t.Errorf("hint should mention --from-user-id, got: %s", p.Hint)
 	}
 }
 
@@ -225,23 +268,20 @@ func TestMinutesSpeakerReplace_NoEditPermission(t *testing.T) {
 		t.Fatal("expected no-edit-permission error, got nil")
 	}
 
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want typed errs.*, got %T: %v", err, err)
 	}
-	if exitErr.Detail == nil {
-		t.Fatalf("expected structured error detail, got nil")
+	if p.Subtype != errs.SubtypePermissionDenied {
+		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
 	}
-	if exitErr.Detail.Type != "no_edit_permission" {
-		t.Errorf("error type = %q, want no_edit_permission", exitErr.Detail.Type)
+	if !strings.Contains(p.Message, "No edit permission") {
+		t.Errorf("message should be friendly, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "No edit permission") {
-		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
+	if !strings.Contains(p.Message, minutesSpeakerReplaceTestToken) {
+		t.Errorf("message should include minute token, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, minutesSpeakerReplaceTestToken) {
-		t.Errorf("message should include minute token, got: %s", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "edit permission") {
+		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
 	}
 }

shortcuts/minutes/minutes_update.go

@@ -5,12 +5,11 @@ package minutes
 
 import (
 	"context"
-	"errors"
 	"fmt"
 	"net/http"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -33,13 +32,13 @@ var MinutesUpdate = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
 		if minuteToken == "" {
-			return output.ErrValidation("--minute-token is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-token is required").WithParam("--minute-token")
 		}
 		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
 		}
 		if strings.TrimSpace(runtime.Str("topic")) == "" {
-			return output.ErrValidation("--topic is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--topic is required").WithParam("--topic")
 		}
 		return nil
 	},
@@ -57,7 +56,7 @@ var MinutesUpdate = common.Shortcut{
 			"topic": topic,
 		}
 
-		_, err := runtime.CallAPI(http.MethodPatch,
+		_, err := runtime.CallAPITyped(http.MethodPatch,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)),
 			nil, body)
 		if err != nil {
@@ -75,20 +74,11 @@ var MinutesUpdate = common.Shortcut{
 }
 
 func minutesUpdateError(err error, minuteToken string) error {
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesUpdateNoEditPermissionCode {
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Code != minutesUpdateNoEditPermissionCode {
 		return err
 	}
-
-	return &output.ExitError{
-		Code: output.ExitAPI,
-		Detail: &output.ErrDetail{
-			Type:    "no_edit_permission",
-			Code:    minutesUpdateNoEditPermissionCode,
-			Message: fmt.Sprintf("No edit permission for minute %q: cannot update the title.", minuteToken),
-			Hint:    "Ask the minute owner for minute edit permission",
-			Detail:  exitErr.Detail.Detail,
-		},
-		Err: err,
-	}
+	p.Message = fmt.Sprintf("No edit permission for minute %q: cannot update the title.", minuteToken)
+	p.Hint = "Ask the minute owner for minute edit permission"
+	return err
 }

shortcuts/minutes/minutes_update_test.go

@@ -9,9 +9,9 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -55,6 +55,32 @@ func TestMinutesUpdate_Validate(t *testing.T) {
 	}
 }
 
+func TestMinutesUpdate_ValidateTyped(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	// ".." triggers ResourceName rejection — hits our Validate, not cobra's required-flag check.
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesUpdate.Mount(parent, f)
+	parent.SetArgs([]string{"+update", "--minute-token", "..", "--topic", "title", "--as", "user"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	err := parent.Execute()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype=%q", ve.Subtype)
+	}
+	if ve.Param != "--minute-token" {
+		t.Errorf("param=%q", ve.Param)
+	}
+}
+
 func TestMinutesUpdate_DryRun(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
@@ -132,23 +158,20 @@ func TestMinutesUpdate_NoEditPermission(t *testing.T) {
 		t.Fatal("expected no-edit-permission error, got nil")
 	}
 
-	var exitErr *output.ExitError
-	if !errors.As(err, &exitErr) {
-		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("want typed errs.*, got %T: %v", err, err)
 	}
-	if exitErr.Detail == nil {
-		t.Fatalf("expected structured error detail, got nil")
+	if p.Subtype != errs.SubtypePermissionDenied {
+		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
 	}
-	if exitErr.Detail.Type != "no_edit_permission" {
-		t.Errorf("error type = %q, want no_edit_permission", exitErr.Detail.Type)
+	if !strings.Contains(p.Message, "No edit permission") {
+		t.Errorf("message should be friendly, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, "No edit permission") {
-		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
+	if !strings.Contains(p.Message, minutesUpdateTestToken) {
+		t.Errorf("message should include minute token, got: %s", p.Message)
 	}
-	if !strings.Contains(exitErr.Detail.Message, minutesUpdateTestToken) {
-		t.Errorf("message should include minute token, got: %s", exitErr.Detail.Message)
-	}
-	if !strings.Contains(exitErr.Detail.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", exitErr.Detail.Hint)
+	if !strings.Contains(p.Hint, "edit permission") {
+		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
 	}
 }

shortcuts/minutes/minutes_upload.go

@@ -6,7 +6,7 @@ package minutes
 import (
 	"context"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -36,10 +36,10 @@ var MinutesUpload = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		fileToken := runtime.Str("file-token")
 		if fileToken == "" {
-			return output.ErrValidation("--file-token is required")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-token is required").WithParam("--file-token")
 		}
 		if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
-			return output.ErrValidation("%s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--file-token")
 		}
 		return nil
 	},
@@ -55,7 +55,7 @@ var MinutesUpload = common.Shortcut{
 			"file_token": fileToken,
 		}
 
-		data, err := runtime.CallAPI("POST", "/open-apis/minutes/v1/minutes/upload", nil, body)
+		data, err := runtime.CallAPITyped("POST", "/open-apis/minutes/v1/minutes/upload", nil, body)
 		if err != nil {
 			return err
 		}

shortcuts/minutes/minutes_upload_test.go

@@ -5,10 +5,12 @@ package minutes
 
 import (
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/spf13/cobra"
@@ -46,6 +48,31 @@ func TestMinutesUpload_Validate(t *testing.T) {
 	}
 }
 
+func TestMinutesUpload_ValidateTyped(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	// ".." triggers ResourceName rejection — hits our Validate, not cobra's required-flag check.
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesUpload.Mount(parent, f)
+	parent.SetArgs([]string{"+upload", "--file-token", "..", "--as", "user"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	err := parent.Execute()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("subtype=%q", ve.Subtype)
+	}
+	if ve.Param != "--file-token" {
+		t.Errorf("param=%q", ve.Param)
+	}
+}
+
 func TestMinutesUpload_HelpMetadata(t *testing.T) {
 	if len(MinutesUpload.Flags) == 0 {
 		t.Fatal("expected file-token flag metadata")

shortcuts/register_test.go

@@ -155,7 +155,7 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }
 
-func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndUpgradeTips(t *testing.T) {
+func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -166,121 +166,111 @@ func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndUpgradeTips(t *testing.T
 	if docsCmd == nil || docsCmd.Name() != "docs" {
 		t.Fatalf("docs command not mounted: %#v", docsCmd)
 	}
-	if docsCmd.Flags().Lookup("api-version") == nil {
-		t.Fatal("docs command should expose --api-version for versioned help")
+	if docsCmd.Flags().Lookup("api-version") != nil {
+		t.Fatal("docs command should not expose service-level --api-version")
 	}
 
 	if !strings.Contains(docsCmd.Long, "Document and content operations.") {
 		t.Fatalf("docs long help missing default description:\n%s", docsCmd.Long)
 	}
 
+	for _, child := range docsCmd.Commands() {
+		if child.Name() == "+get-skill" {
+			t.Fatal("docs +get-skill should not be mounted")
+		}
+	}
+
 	var defaultHelp bytes.Buffer
 	docsCmd.SetOut(&defaultHelp)
 	if err := docsCmd.Help(); err != nil {
 		t.Fatalf("docs help failed: %v", err)
 	}
 	for _, want := range []string{
-		"Tips:",
-		"Docs v1 is deprecated and will be removed soon",
-		"Check the installed lark-doc skill first",
-		"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
-		"After confirming lark-doc is v2",
-		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+		"Start here (required for AI agents):",
+		"lark-cli skills read lark-doc",
+		"AI agents MUST read the matching embedded skill",
+		"Do not skip this step",
+		"MUST NOT grep/open local SKILL.md files",
 	} {
 		if !strings.Contains(defaultHelp.String(), want) {
 			t.Fatalf("docs default help missing %q:\n%s", want, defaultHelp.String())
 		}
 	}
-}
-
-func TestRegisterShortcutsDocsV2HelpUsesV2Description(t *testing.T) {
-	program := &cobra.Command{Use: "root"}
-	RegisterShortcuts(program, newRegisterTestFactory(t))
-
-	docsCmd, _, err := program.Find([]string{"docs"})
-	if err != nil {
-		t.Fatalf("find docs command: %v", err)
-	}
-	if err := docsCmd.Flags().Set("api-version", "v2"); err != nil {
-		t.Fatalf("set docs api-version: %v", err)
-	}
-
-	var out bytes.Buffer
-	docsCmd.SetOut(&out)
-	if err := docsCmd.Help(); err != nil {
-		t.Fatalf("docs v2 help failed: %v", err)
-	}
-
-	for _, want := range []string{
-		"Document and content operations (v2).",
-		"Tips:",
-		"Check the installed lark-doc skill first",
-		"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
-	} {
-		if !strings.Contains(out.String(), want) {
-			t.Fatalf("docs v2 help missing %q:\n%s", want, out.String())
-		}
+	if startIdx, usageIdx := strings.Index(defaultHelp.String(), "Start here (required for AI agents):"), strings.Index(defaultHelp.String(), "Usage:"); startIdx < 0 || usageIdx < 0 || startIdx > usageIdx {
+		t.Fatalf("docs help should show Start here before Usage:\n%s", defaultHelp.String())
 	}
 	for _, unwanted := range []string{
+		"Tips:",
+		"+get-skill",
+		"Docs shortcuts are v2-only",
 		"Docs v1 is deprecated and will be removed soon",
-		"After confirming lark-doc is v2",
-		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+		"lark-cli update",
+		"upgrade skills",
+		"Use --api-version v2 for the latest API",
 	} {
-		if strings.Contains(out.String(), unwanted) {
-			t.Fatalf("docs v2 help should not include %q:\n%s", unwanted, out.String())
+		if strings.Contains(defaultHelp.String(), unwanted) {
+			t.Fatalf("docs help should not include %q:\n%s", unwanted, defaultHelp.String())
 		}
 	}
 }
 
-func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T) {
+func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 	tests := []struct {
-		name          string
-		shortcut      string
-		apiVersion    string
-		shortcutHelp  string
-		versionedFlag string
+		name         string
+		shortcut     string
+		shortcutHelp string
+		visibleFlag  string
+		skillCommand string
+		hiddenFlags  []string
+		contentHelp  []string
+		unwanted     []string
 	}{
 		{
-			name:          "create v1",
-			shortcut:      "+create",
-			apiVersion:    "v1",
-			shortcutHelp:  "Create a Lark document",
-			versionedFlag: "--markdown",
+			name:         "create",
+			shortcut:     "+create",
+			shortcutHelp: "Create a Lark document",
+			visibleFlag:  "--content",
+			skillCommand: "lark-cli skills read lark-doc references/lark-doc-create.md",
+			hiddenFlags:  []string{"title", "markdown", "folder-token", "wiki-node", "wiki-space"},
+			contentHelp: []string{
+				"AI agents MUST read",
+				"lark-cli skills read lark-doc references/lark-doc-xml.md",
+				"before writing any --content payload",
+				"when using --doc-format markdown, also read",
+				"lark-cli skills read lark-doc references/lark-doc-md.md",
+				"Follow the latest rules",
+				"MUST NOT grep/open local SKILL.md files",
+				"use --help for the latest command flags",
+			},
+			unwanted: []string{"--markdown", "--title", "--folder-token", "--wiki-node", "--wiki-space"},
 		},
 		{
-			name:          "create v2",
-			shortcut:      "+create",
-			apiVersion:    "v2",
-			shortcutHelp:  "Create a Lark document",
-			versionedFlag: "--content",
+			name:         "fetch",
+			shortcut:     "+fetch",
+			shortcutHelp: "Fetch Lark document content",
+			visibleFlag:  "read scope",
+			skillCommand: "lark-cli skills read lark-doc references/lark-doc-fetch.md",
+			hiddenFlags:  []string{"offset", "limit"},
+			unwanted:     []string{"--offset", "--limit"},
 		},
 		{
-			name:          "fetch v1",
-			shortcut:      "+fetch",
-			apiVersion:    "v1",
-			shortcutHelp:  "Fetch Lark document content",
-			versionedFlag: "--offset",
-		},
-		{
-			name:          "fetch v2",
-			shortcut:      "+fetch",
-			apiVersion:    "v2",
-			shortcutHelp:  "Fetch Lark document content",
-			versionedFlag: "partial read scope",
-		},
-		{
-			name:          "update v1",
-			shortcut:      "+update",
-			apiVersion:    "v1",
-			shortcutHelp:  "Update a Lark document",
-			versionedFlag: "--mode",
-		},
-		{
-			name:          "update v2",
-			shortcut:      "+update",
-			apiVersion:    "v2",
-			shortcutHelp:  "Update a Lark document",
-			versionedFlag: "--command",
+			name:         "update",
+			shortcut:     "+update",
+			shortcutHelp: "Update a Lark document",
+			visibleFlag:  "--command",
+			skillCommand: "lark-cli skills read lark-doc references/lark-doc-update.md",
+			hiddenFlags:  []string{"mode", "markdown", "selection-with-ellipsis", "selection-by-title", "new-title"},
+			contentHelp: []string{
+				"AI agents MUST read",
+				"lark-cli skills read lark-doc references/lark-doc-xml.md",
+				"before writing any --content payload",
+				"when using --doc-format markdown, also read",
+				"lark-cli skills read lark-doc references/lark-doc-md.md",
+				"Follow the latest rules",
+				"MUST NOT grep/open local SKILL.md files",
+				"use --help for the latest command flags",
+			},
+			unwanted: []string{"--mode", "--markdown", "--selection-with-ellipsis", "--selection-by-title", "--new-title"},
 		},
 	}
 
@@ -296,8 +286,25 @@ func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T)
 			if cmd == nil || cmd.Name() != tt.shortcut {
 				t.Fatalf("docs %s shortcut not mounted: %#v", tt.shortcut, cmd)
 			}
-			if err := cmd.Flags().Set("api-version", tt.apiVersion); err != nil {
-				t.Fatalf("set docs %s api-version: %v", tt.shortcut, err)
+
+			for _, flagName := range tt.hiddenFlags {
+				flag := cmd.Flags().Lookup(flagName)
+				if flag == nil {
+					t.Fatalf("docs %s missing hidden compatibility flag %q", tt.shortcut, flagName)
+				}
+				if !flag.Hidden {
+					t.Fatalf("docs %s flag %q should be hidden", tt.shortcut, flagName)
+				}
+			}
+			apiVersionFlag := cmd.Flags().Lookup("api-version")
+			if apiVersionFlag == nil {
+				t.Fatalf("docs %s missing --api-version flag", tt.shortcut)
+			}
+			if apiVersionFlag.Hidden {
+				t.Fatalf("docs %s --api-version should be visible", tt.shortcut)
+			}
+			if apiVersionFlag.DefValue != "v2" {
+				t.Fatalf("docs %s --api-version default = %q, want v2", tt.shortcut, apiVersionFlag.DefValue)
 			}
 
 			var out bytes.Buffer
@@ -306,49 +313,39 @@ func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T)
 				t.Fatalf("docs %s help failed: %v", tt.shortcut, err)
 			}
 
-			wantTips := []string{
-				"Tips:",
-				"Docs v1 is deprecated and will be removed soon",
-				"Check the installed lark-doc skill first",
-				"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
-				"After confirming lark-doc is v2",
-				"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
-			}
-			unwantedTips := []string{
-				"[NOTE]",
-				"Use --api-version v2 for the latest API",
-				"otherwise use the default v1 flags",
-				"legacy v1 examples and flags",
-			}
-			if tt.apiVersion == "v2" {
-				wantTips = []string{
-					"Tips:",
-					"Check the installed lark-doc skill first",
-					"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
-				}
-				unwantedTips = append(unwantedTips,
-					"Docs v1 is deprecated and will be removed soon",
-					"After confirming lark-doc is v2",
-					"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
-				)
-			}
-
 			for _, want := range []string{
 				tt.shortcutHelp,
-				tt.versionedFlag,
+				tt.visibleFlag,
+				"--api-version",
+				"deprecated compatibility flag; docs shortcuts always use v2",
+				"both v1/v2 are accepted",
+				"(default \"v2\")",
+				"Start here (required for AI agents):",
+				"AI agents MUST read the matching embedded skill",
+				"Do not skip this step",
+				"MUST NOT grep/open local SKILL.md files",
+				tt.skillCommand,
 			} {
 				if !strings.Contains(out.String(), want) {
-					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
+					t.Fatalf("docs %s help missing %q:\n%s", tt.shortcut, want, out.String())
 				}
 			}
-			for _, want := range wantTips {
+			for _, want := range tt.contentHelp {
 				if !strings.Contains(out.String(), want) {
-					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
+					t.Fatalf("docs %s content help missing %q:\n%s", tt.shortcut, want, out.String())
 				}
 			}
-			for _, unwanted := range unwantedTips {
+			if startIdx, usageIdx := strings.Index(out.String(), "Start here (required for AI agents):"), strings.Index(out.String(), "Usage:"); startIdx < 0 || usageIdx < 0 || startIdx > usageIdx {
+				t.Fatalf("docs %s help should show Start here before Usage:\n%s", tt.shortcut, out.String())
+			}
+			for _, unwanted := range []string{"Tips:", "+get-skill", "Docs shortcuts are v2-only"} {
 				if strings.Contains(out.String(), unwanted) {
-					t.Fatalf("docs %s %s help should not include %q:\n%s", tt.shortcut, tt.apiVersion, unwanted, out.String())
+					t.Fatalf("docs %s help should not include %q:\n%s", tt.shortcut, unwanted, out.String())
+				}
+			}
+			for _, unwanted := range tt.unwanted {
+				if strings.Contains(out.String(), unwanted) {
+					t.Fatalf("docs %s help should not include %q:\n%s", tt.shortcut, unwanted, out.String())
 				}
 			}
 		})

shortcuts/sheets/backward/helpers.go

@@ -9,7 +9,7 @@ import (
 	"strconv"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -27,7 +27,7 @@ var sheetRangeSeparatorReplacer = strings.NewReplacer(`\！`, "!", `\!`, "!", "
 
 // getFirstSheetID queries the spreadsheet and returns the first sheet's ID.
 func getFirstSheetID(runtime *common.RuntimeContext, spreadsheetToken string) (string, error) {
-	data, err := runtime.CallAPI("GET", fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/query", validate.EncodePathSegment(spreadsheetToken)), nil, nil)
+	data, err := runtime.CallAPITyped("GET", fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/query", validate.EncodePathSegment(spreadsheetToken)), nil, nil)
 	if err != nil {
 		return "", err
 	}
@@ -38,7 +38,7 @@ func getFirstSheetID(runtime *common.RuntimeContext, spreadsheetToken string) (s
 			return id, nil
 		}
 	}
-	return "", output.Errorf(output.ExitAPI, "not_found", "no sheets found in this spreadsheet")
+	return "", errs.NewValidationError(errs.SubtypeFailedPrecondition, "no sheets found in this spreadsheet")
 }
 
 // extractSpreadsheetToken extracts spreadsheet token from URL.
@@ -104,7 +104,7 @@ func validateSheetRangeInput(sheetID, input string) error {
 		return nil
 	}
 	if looksLikeRelativeRange(input) {
-		return common.FlagErrorf("--range %q requires --sheet-id or a <sheetId>! prefix", input)
+		return common.ValidationErrorf("--range %q requires --sheet-id or a <sheetId>! prefix", input)
 	}
 	return nil
 }
@@ -127,7 +127,7 @@ func validateSingleCellRange(input string) error {
 		if strings.EqualFold(parts[0], parts[1]) {
 			return nil
 		}
-		return common.FlagErrorf("--range %q must be a single cell (e.g. A1 or A1:A1), got a multi-cell span", input)
+		return common.ValidationErrorf("--range %q must be a single cell (e.g. A1 or A1:A1), got a multi-cell span", input)
 	}
 	return nil
 }
@@ -197,11 +197,11 @@ func matrixDimensions(values interface{}) (rows, cols int) {
 func offsetCell(cell string, rowOffset, colOffset int) (string, error) {
 	matches := cellRefPattern.FindStringSubmatch(strings.TrimSpace(cell))
 	if len(matches) != 3 {
-		return "", fmt.Errorf("invalid cell reference: %s", cell)
+		return "", fmt.Errorf("invalid cell reference: %s", cell) //nolint:forbidigo // intermediate sentinel; sole caller buildRectRange discards it and falls back
 	}
 	colIndex := columnNameToIndex(matches[1])
 	if colIndex < 1 {
-		return "", fmt.Errorf("invalid column: %s", matches[1])
+		return "", fmt.Errorf("invalid column: %s", matches[1]) //nolint:forbidigo // intermediate sentinel; sole caller buildRectRange discards it and falls back
 	}
 	rowIndex, err := strconv.Atoi(matches[2])
 	if err != nil {

shortcuts/sheets/backward/lark_sheets_cell_data.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -15,10 +16,10 @@ import (
 func parseValues2DJSON(raw string) ([][]interface{}, error) {
 	var rows [][]interface{}
 	if err := json.Unmarshal([]byte(raw), &rows); err != nil {
-		return nil, common.FlagErrorf("--values invalid JSON, must be a 2D array")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--values invalid JSON, must be a 2D array").WithParam("--values")
 	}
 	if rows == nil {
-		return nil, common.FlagErrorf("--values invalid JSON, must be a 2D array")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--values invalid JSON, must be a 2D array").WithParam("--values")
 	}
 	return rows, nil
 }
@@ -46,7 +47,7 @@ var SheetRead = common.Shortcut{
 		}
 		if r := runtime.Str("range"); r != "" {
 			if rangeSheetID, _, ok := splitSheetRange(r); ok && runtime.Str("sheet-id") != "" && rangeSheetID != runtime.Str("sheet-id") {
-				return common.FlagErrorf("--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id"))
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id")).WithParam("--range")
 			}
 		}
 		return nil
@@ -90,7 +91,7 @@ var SheetRead = common.Shortcut{
 			params["valueRenderOption"] = renderOption
 		}
 
-		data, err := runtime.CallAPI("GET", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values/%s", validate.EncodePathSegment(token), validate.EncodePathSegment(readRange)), params, nil)
+		data, err := runtime.CallAPITyped("GET", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values/%s", validate.EncodePathSegment(token), validate.EncodePathSegment(readRange)), params, nil)
 		if err != nil {
 			return err
 		}
@@ -167,7 +168,7 @@ var SheetWrite = common.Shortcut{
 			writeRange = normalizeWriteRange(runtime.Str("sheet-id"), writeRange, values)
 		}
 
-		data, err := runtime.CallAPI("PUT", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values", validate.EncodePathSegment(token)), nil, map[string]interface{}{
+		data, err := runtime.CallAPITyped("PUT", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values", validate.EncodePathSegment(token)), nil, map[string]interface{}{
 			"valueRange": map[string]interface{}{
 				"range":  writeRange,
 				"values": values,
@@ -247,7 +248,7 @@ var SheetAppend = common.Shortcut{
 			appendRange = normalizePointRange(runtime.Str("sheet-id"), appendRange)
 		}
 
-		data, err := runtime.CallAPI("POST", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values_append", validate.EncodePathSegment(token)), nil, map[string]interface{}{
+		data, err := runtime.CallAPITyped("POST", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values_append", validate.EncodePathSegment(token)), nil, map[string]interface{}{
 			"valueRange": map[string]interface{}{
 				"range":  appendRange,
 				"values": values,
@@ -288,7 +289,7 @@ var SheetFind = common.Shortcut{
 		}
 		if r := runtime.Str("range"); r != "" {
 			if rangeSheetID, _, ok := splitSheetRange(r); ok && runtime.Str("sheet-id") != "" && rangeSheetID != runtime.Str("sheet-id") {
-				return common.FlagErrorf("--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id"))
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id")).WithParam("--range")
 			}
 		}
 		return nil
@@ -336,7 +337,7 @@ var SheetFind = common.Shortcut{
 			"find":           findText,
 		}
 
-		data, err := runtime.CallAPI("POST", fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/%s/find", validate.EncodePathSegment(token), validate.EncodePathSegment(sheetID)), nil, reqData)
+		data, err := runtime.CallAPITyped("POST", fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/%s/find", validate.EncodePathSegment(token), validate.EncodePathSegment(sheetID)), nil, reqData)
 		if err != nil {
 			return err
 		}
@@ -373,7 +374,7 @@ var SheetReplace = common.Shortcut{
 		}
 		if r := runtime.Str("range"); r != "" {
 			if rangeSheetID, _, ok := splitSheetRange(r); ok && runtime.Str("sheet-id") != "" && rangeSheetID != runtime.Str("sheet-id") {
-				return common.FlagErrorf("--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id"))
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range sheet ID %q does not match --sheet-id %q", rangeSheetID, runtime.Str("sheet-id")).WithParam("--range")
 			}
 		}
 		return nil
@@ -415,7 +416,7 @@ var SheetReplace = common.Shortcut{
 			findCondition["range"] = normalizeSheetRange(sheetID, runtime.Str("range"))
 		}
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/%s/replace",
 				validate.EncodePathSegment(token),
 				validate.EncodePathSegment(sheetID),

shortcuts/sheets/backward/lark_sheets_cell_images.go

@@ -11,8 +11,8 @@ import (
 	"os"
 	"path/filepath"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -38,7 +38,7 @@ var SheetWriteImage = common.Shortcut{
 			token = extractSpreadsheetToken(runtime.Str("url"))
 		}
 		if token == "" {
-			return common.FlagErrorf("specify --url or --spreadsheet-token")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 		}
 		if err := validateSheetRangeInput(runtime.Str("sheet-id"), runtime.Str("range")); err != nil {
 			return err
@@ -91,7 +91,7 @@ var SheetWriteImage = common.Shortcut{
 
 		imageBytes, err := io.ReadAll(imageFile)
 		if err != nil {
-			return output.ErrValidation("cannot read image file: %s", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot read image file: %s", err).WithParam("--image").WithCause(err)
 		}
 
 		imageName := runtime.Str("name")
@@ -101,7 +101,7 @@ var SheetWriteImage = common.Shortcut{
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Writing image: %s (%d bytes) → %s\n", imageName, stat.Size(), pointRange)
 
-		data, err := runtime.CallAPI("POST", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values_image", validate.EncodePathSegment(token)), nil, map[string]interface{}{
+		data, err := runtime.CallAPITyped("POST", fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/values_image", validate.EncodePathSegment(token)), nil, map[string]interface{}{
 			"range": pointRange,
 			"image": imageBytes,
 			"name":  imageName,
@@ -116,35 +116,35 @@ var SheetWriteImage = common.Shortcut{
 
 func validateSheetWriteImageFile(fio fileio.FileIO, imagePath string) (fileio.FileInfo, error) {
 	if fio == nil {
-		return nil, output.ErrValidation("no file I/O provider registered")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "no file I/O provider registered")
 	}
 	stat, err := fio.Stat(imagePath)
 	if err != nil {
 		return nil, wrapSheetWriteImageStatError(err, imagePath)
 	}
 	if stat.IsDir() || !stat.Mode().IsRegular() {
-		return nil, output.ErrValidation("image must be a regular file: %s", imagePath)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "image must be a regular file: %s", imagePath).WithParam("--image")
 	}
 	const maxImageSize int64 = 20 * 1024 * 1024
 	if stat.Size() > maxImageSize {
-		return nil, output.ErrValidation("image %.1fMB exceeds 20MB limit", float64(stat.Size())/1024/1024)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "image %.1fMB exceeds 20MB limit", float64(stat.Size())/1024/1024).WithParam("--image")
 	}
 	return stat, nil
 }
 
 func wrapSheetWriteImageStatError(err error, imagePath string) error {
 	if errors.Is(err, fileio.ErrPathValidation) {
-		return output.ErrValidation("unsafe image path: %s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe image path: %s", err).WithParam("--image").WithCause(err)
 	}
 	if os.IsNotExist(err) {
-		return output.ErrValidation("image file not found: %s", imagePath)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "image file not found: %s", imagePath).WithParam("--image").WithCause(err)
 	}
-	return output.ErrValidation("cannot stat image file: %s", err)
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot stat image file: %s", err).WithParam("--image").WithCause(err)
 }
 
 func wrapSheetWriteImageOpenError(err error) error {
 	if errors.Is(err, fileio.ErrPathValidation) {
-		return output.ErrValidation("unsafe image path: %s", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe image path: %s", err).WithParam("--image").WithCause(err)
 	}
-	return output.ErrValidation("cannot read image file: %s", err)
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot read image file: %s", err).WithParam("--image").WithCause(err)
 }

shortcuts/sheets/backward/lark_sheets_cell_style_and_merge.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -15,40 +16,40 @@ import (
 func validateBatchStyleData(raw string) error {
 	var data interface{}
 	if err := json.Unmarshal([]byte(raw), &data); err != nil {
-		return common.FlagErrorf("--data must be valid JSON: %v", err)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be valid JSON: %v", err).WithParam("--data")
 	}
 	arr, ok := data.([]interface{})
 	if !ok || len(arr) == 0 {
-		return common.FlagErrorf("--data must be a non-empty JSON array")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be a non-empty JSON array").WithParam("--data")
 	}
 	for i, item := range arr {
 		entry, ok := item.(map[string]interface{})
 		if !ok {
-			return common.FlagErrorf("--data[%d] must be an object with ranges and style", i)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d] must be an object with ranges and style", i).WithParam("--data")
 		}
 		rangesRaw, ok := entry["ranges"]
 		if !ok {
-			return common.FlagErrorf("--data[%d].ranges is required", i)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].ranges is required", i).WithParam("--data")
 		}
 		ranges, ok := rangesRaw.([]interface{})
 		if !ok || len(ranges) == 0 {
-			return common.FlagErrorf("--data[%d].ranges must be a non-empty array of strings", i)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].ranges must be a non-empty array of strings", i).WithParam("--data")
 		}
 		for j, r := range ranges {
 			s, ok := r.(string)
 			if !ok || s == "" {
-				return common.FlagErrorf("--data[%d].ranges[%d] must be a non-empty string", i, j)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].ranges[%d] must be a non-empty string", i, j).WithParam("--data")
 			}
 			if _, _, ok := splitSheetRange(s); !ok {
-				return common.FlagErrorf("--data[%d].ranges[%d] %q must include a sheetId! prefix", i, j, s)
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].ranges[%d] %q must include a sheetId! prefix", i, j, s).WithParam("--data")
 			}
 		}
 		styleRaw, ok := entry["style"]
 		if !ok {
-			return common.FlagErrorf("--data[%d].style is required", i)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].style is required", i).WithParam("--data")
 		}
 		if _, ok := styleRaw.(map[string]interface{}); !ok {
-			return common.FlagErrorf("--data[%d].style must be a JSON object", i)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data[%d].style must be a JSON object", i).WithParam("--data")
 		}
 	}
 	return nil
@@ -74,14 +75,14 @@ var SheetSetStyle = common.Shortcut{
 			token = extractSpreadsheetToken(runtime.Str("url"))
 		}
 		if token == "" {
-			return common.FlagErrorf("specify --url or --spreadsheet-token")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 		}
 		var style interface{}
 		if err := json.Unmarshal([]byte(runtime.Str("style")), &style); err != nil {
-			return common.FlagErrorf("--style must be valid JSON: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be valid JSON: %v", err).WithParam("--style")
 		}
 		if _, ok := style.(map[string]interface{}); !ok {
-			return common.FlagErrorf("--style must be a JSON object, got %T", style)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be a JSON object, got %T", style).WithParam("--style")
 		}
 		if err := validateSheetRangeInput(runtime.Str("sheet-id"), runtime.Str("range")); err != nil {
 			return err
@@ -115,10 +116,10 @@ var SheetSetStyle = common.Shortcut{
 		r := normalizePointRange(runtime.Str("sheet-id"), runtime.Str("range"))
 		var style interface{}
 		if err := json.Unmarshal([]byte(runtime.Str("style")), &style); err != nil {
-			return common.FlagErrorf("--style must be valid JSON: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be valid JSON: %v", err).WithParam("--style")
 		}
 
-		data, err := runtime.CallAPI("PUT",
+		data, err := runtime.CallAPITyped("PUT",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/style", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{
@@ -154,7 +155,7 @@ var SheetBatchSetStyle = common.Shortcut{
 			token = extractSpreadsheetToken(runtime.Str("url"))
 		}
 		if token == "" {
-			return common.FlagErrorf("specify --url or --spreadsheet-token")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 		}
 		return validateBatchStyleData(runtime.Str("data"))
 	},
@@ -181,11 +182,11 @@ var SheetBatchSetStyle = common.Shortcut{
 
 		var data interface{}
 		if err := json.Unmarshal([]byte(runtime.Str("data")), &data); err != nil {
-			return common.FlagErrorf("--data must be valid JSON: %v", err)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be valid JSON: %v", err).WithParam("--data")
 		}
 		normalizeBatchStyleRanges(data)
 
-		result, err := runtime.CallAPI("PUT",
+		result, err := runtime.CallAPITyped("PUT",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/styles_batch_update", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{
@@ -242,7 +243,7 @@ var SheetMergeCells = common.Shortcut{
 			token = extractSpreadsheetToken(runtime.Str("url"))
 		}
 		if token == "" {
-			return common.FlagErrorf("specify --url or --spreadsheet-token")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 		}
 		if err := validateSheetRangeInput(runtime.Str("sheet-id"), runtime.Str("range")); err != nil {
 			return err
@@ -271,7 +272,7 @@ var SheetMergeCells = common.Shortcut{
 
 		r := normalizeSheetRange(runtime.Str("sheet-id"), runtime.Str("range"))
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/merge_cells", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{
@@ -306,7 +307,7 @@ var SheetUnmergeCells = common.Shortcut{
 			token = extractSpreadsheetToken(runtime.Str("url"))
 		}
 		if token == "" {
-			return common.FlagErrorf("specify --url or --spreadsheet-token")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 		}
 		if err := validateSheetRangeInput(runtime.Str("sheet-id"), runtime.Str("range")); err != nil {
 			return err
@@ -334,7 +335,7 @@ var SheetUnmergeCells = common.Shortcut{
 
 		r := normalizeSheetRange(runtime.Str("sheet-id"), runtime.Str("range"))
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/unmerge_cells", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{

shortcuts/sheets/backward/lark_sheets_dropdown.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -27,7 +28,7 @@ func validateDropdownToken(runtime *common.RuntimeContext) (string, error) {
 		token = extractSpreadsheetToken(runtime.Str("url"))
 	}
 	if token == "" {
-		return "", common.FlagErrorf("specify --url or --spreadsheet-token")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 	}
 	return token, nil
 }
@@ -35,10 +36,10 @@ func validateDropdownToken(runtime *common.RuntimeContext) (string, error) {
 func parseJSONStringArray(flagName, value string) ([]interface{}, error) {
 	var typed []string
 	if err := json.Unmarshal([]byte(value), &typed); err != nil {
-		return nil, common.FlagErrorf("--%s must be a JSON array of strings: %v", flagName, err)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s must be a JSON array of strings: %v", flagName, err).WithParam("--" + flagName)
 	}
 	if typed == nil {
-		return nil, common.FlagErrorf("--%s must be a JSON array, got null", flagName)
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s must be a JSON array, got null", flagName).WithParam("--" + flagName)
 	}
 	arr := make([]interface{}, len(typed))
 	for i, s := range typed {
@@ -53,12 +54,12 @@ func validateRangesFlag(runtime *common.RuntimeContext) ([]interface{}, error) {
 		return nil, err
 	}
 	if len(ranges) == 0 {
-		return nil, common.FlagErrorf("--ranges must not be empty")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--ranges must not be empty").WithParam("--ranges")
 	}
 	for i, r := range ranges {
 		s, _ := r.(string)
 		if _, _, ok := splitSheetRange(s); !ok {
-			return nil, common.FlagErrorf("--ranges[%d] %q must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)", i, s)
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--ranges[%d] %q must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)", i, s).WithParam("--ranges")
 		}
 	}
 	return ranges, nil
@@ -70,7 +71,7 @@ func buildDropdownBody(runtime *common.RuntimeContext) (map[string]interface{},
 		return nil, err
 	}
 	if len(condValues) == 0 {
-		return nil, common.FlagErrorf("--condition-values must not be empty")
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--condition-values must not be empty").WithParam("--condition-values")
 	}
 
 	dv := map[string]interface{}{
@@ -90,7 +91,7 @@ func buildDropdownBody(runtime *common.RuntimeContext) (map[string]interface{},
 			return nil, err
 		}
 		if len(colors) != len(condValues) {
-			return nil, common.FlagErrorf("--colors length (%d) must match --condition-values length (%d)", len(colors), len(condValues))
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--colors length (%d) must match --condition-values length (%d)", len(colors), len(condValues)).WithParam("--colors")
 		}
 		opts["colors"] = colors
 	}
@@ -123,7 +124,7 @@ var SheetSetDropdown = common.Shortcut{
 			return err
 		}
 		if _, _, ok := splitSheetRange(runtime.Str("range")); !ok {
-			return common.FlagErrorf("--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)").WithParam("--range")
 		}
 		_, err := buildDropdownBody(runtime)
 		return err
@@ -147,7 +148,7 @@ var SheetSetDropdown = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPI("POST", dataValidationBasePath(token), nil,
+		data, err := runtime.CallAPITyped("POST", dataValidationBasePath(token), nil,
 			map[string]interface{}{
 				"range":              runtime.Str("range"),
 				"dataValidationType": "list",
@@ -214,7 +215,7 @@ var SheetUpdateDropdown = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPI("PUT", dataValidationSheetPath(token, runtime.Str("sheet-id")), nil,
+		data, err := runtime.CallAPITyped("PUT", dataValidationSheetPath(token, runtime.Str("sheet-id")), nil,
 			map[string]interface{}{
 				"ranges":             ranges,
 				"dataValidationType": "list",
@@ -247,7 +248,7 @@ var SheetGetDropdown = common.Shortcut{
 			return err
 		}
 		if _, _, ok := splitSheetRange(runtime.Str("range")); !ok {
-			return common.FlagErrorf("--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range must be a fully qualified range with sheet ID prefix (e.g. <sheetId>!A2:A100)").WithParam("--range")
 		}
 		return nil
 	},
@@ -259,7 +260,7 @@ var SheetGetDropdown = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateDropdownToken(runtime)
-		data, err := runtime.CallAPI("GET", dataValidationBasePath(token),
+		data, err := runtime.CallAPITyped("GET", dataValidationBasePath(token),
 			map[string]interface{}{
 				"range":              runtime.Str("range"),
 				"dataValidationType": "list",
@@ -319,7 +320,7 @@ var SheetDeleteDropdown = common.Shortcut{
 			dvRanges = append(dvRanges, map[string]interface{}{"range": r})
 		}
 
-		data, err := runtime.CallAPI("DELETE", dataValidationBasePath(token), nil,
+		data, err := runtime.CallAPITyped("DELETE", dataValidationBasePath(token), nil,
 			map[string]interface{}{
 				"dataValidationRanges": dvRanges,
 			},

shortcuts/sheets/backward/lark_sheets_filter_views.go

@@ -9,7 +9,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -59,7 +59,7 @@ var SheetCreateFilterView = common.Shortcut{
 			return err
 		}
 		if strings.TrimSpace(runtime.Str("range")) == "" {
-			return common.FlagErrorf("--range must not be empty")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range must not be empty").WithParam("--range")
 		}
 		return nil
 	},
@@ -85,7 +85,7 @@ var SheetCreateFilterView = common.Shortcut{
 		if s := runtime.Str("filter-view-id"); s != "" {
 			body["filter_view_id"] = s
 		}
-		data, err := runtime.CallAPI("POST", filterViewBasePath(token, runtime.Str("sheet-id")), nil, body)
+		data, err := runtime.CallAPITyped("POST", filterViewBasePath(token, runtime.Str("sheet-id")), nil, body)
 		if err != nil {
 			return err
 		}
@@ -115,7 +115,7 @@ var SheetUpdateFilterView = common.Shortcut{
 		}
 		if !hasNonEmptyStringFlag(runtime, "range") &&
 			!hasNonEmptyStringFlag(runtime, "filter-view-name") {
-			return common.FlagErrorf("specify at least one of --range or --filter-view-name")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --range or --filter-view-name")
 		}
 		return nil
 	},
@@ -141,7 +141,7 @@ var SheetUpdateFilterView = common.Shortcut{
 		if s := runtime.Str("filter-view-name"); s != "" {
 			body["filter_view_name"] = s
 		}
-		data, err := runtime.CallAPI("PATCH", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
+		data, err := runtime.CallAPITyped("PATCH", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
 		if err != nil {
 			return err
 		}
@@ -174,7 +174,7 @@ var SheetListFilterViews = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("GET", filterViewBasePath(token, runtime.Str("sheet-id"))+"/query", nil, nil)
+		data, err := runtime.CallAPITyped("GET", filterViewBasePath(token, runtime.Str("sheet-id"))+"/query", nil, nil)
 		if err != nil {
 			return err
 		}
@@ -208,7 +208,7 @@ var SheetGetFilterView = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("GET", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
+		data, err := runtime.CallAPITyped("GET", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
 		if err != nil {
 			return err
 		}
@@ -242,7 +242,7 @@ var SheetDeleteFilterView = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("DELETE", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
+		data, err := runtime.CallAPITyped("DELETE", filterViewItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, nil)
 		if err != nil {
 			return err
 		}
@@ -284,7 +284,7 @@ var SheetCreateFilterViewCondition = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
 		body := buildConditionBody(runtime, true)
-		data, err := runtime.CallAPI("POST", filterViewConditionBasePath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
+		data, err := runtime.CallAPITyped("POST", filterViewConditionBasePath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id")), nil, body)
 		if err != nil {
 			return err
 		}
@@ -317,7 +317,7 @@ var SheetUpdateFilterViewCondition = common.Shortcut{
 		if !hasNonEmptyStringFlag(runtime, "filter-type") &&
 			!hasNonEmptyStringFlag(runtime, "compare-type") &&
 			!hasNonEmptyStringFlag(runtime, "expected") {
-			return common.FlagErrorf("specify at least one of --filter-type, --compare-type, or --expected")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --filter-type, --compare-type, or --expected")
 		}
 		if s := runtime.Str("expected"); s != "" {
 			return validateExpectedFlag(s)
@@ -335,7 +335,7 @@ var SheetUpdateFilterViewCondition = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
 		body := buildConditionBody(runtime, false)
-		data, err := runtime.CallAPI("PUT",
+		data, err := runtime.CallAPITyped("PUT",
 			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
 			nil, body)
 		if err != nil {
@@ -371,7 +371,7 @@ var SheetListFilterViewConditions = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("GET",
+		data, err := runtime.CallAPITyped("GET",
 			filterViewConditionBasePath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"))+"/query",
 			nil, nil)
 		if err != nil {
@@ -409,7 +409,7 @@ var SheetGetFilterViewCondition = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("GET",
+		data, err := runtime.CallAPITyped("GET",
 			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
 			nil, nil)
 		if err != nil {
@@ -447,7 +447,7 @@ var SheetDeleteFilterViewCondition = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFilterViewToken(runtime)
-		data, err := runtime.CallAPI("DELETE",
+		data, err := runtime.CallAPITyped("DELETE",
 			filterViewConditionItemPath(token, runtime.Str("sheet-id"), runtime.Str("filter-view-id"), runtime.Str("condition-id")),
 			nil, nil)
 		if err != nil {
@@ -464,7 +464,7 @@ func validateExpectedFlag(s string) error {
 	}
 	var arr []interface{}
 	if err := json.Unmarshal([]byte(s), &arr); err != nil {
-		return output.ErrValidation("--expected must be a JSON array (e.g. [\"6\"]), got: %s", s)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--expected must be a JSON array (e.g. [\"6\"]), got: %s", s).WithParam("--expected")
 	}
 	return nil
 }

shortcuts/sheets/backward/lark_sheets_float_images.go

@@ -8,8 +8,8 @@ import (
 	"fmt"
 	"path/filepath"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -115,10 +115,10 @@ var SheetMediaUpload = common.Shortcut{
 func validateSheetMediaUploadFile(runtime *common.RuntimeContext, filePath string) (string, fileio.FileInfo, error) {
 	stat, err := runtime.FileIO().Stat(filePath)
 	if err != nil {
-		return "", nil, common.WrapInputStatError(err, "file not found")
+		return "", nil, common.WrapInputStatErrorTyped(err, "file not found")
 	}
 	if !stat.Mode().IsRegular() {
-		return "", nil, output.ErrValidation("file must be a regular file: %s", filePath)
+		return "", nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "file must be a regular file: %s", filePath).WithParam("--file")
 	}
 	return filePath, stat, nil
 }
@@ -131,7 +131,7 @@ func resolveSheetMediaUploadParent(runtime *common.RuntimeContext) (string, erro
 		}
 	}
 	if token == "" {
-		return "", common.FlagErrorf("specify --url or --spreadsheet-token")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 	}
 	return token, nil
 }
@@ -181,7 +181,7 @@ func validateFloatImageToken(runtime *common.RuntimeContext) (string, error) {
 		}
 	}
 	if token == "" {
-		return "", common.FlagErrorf("specify --url or --spreadsheet-token")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --url or --spreadsheet-token")
 	}
 	return token, nil
 }
@@ -194,7 +194,7 @@ func validateFloatImageRange(sheetID, rangeVal string) error {
 		return err
 	}
 	if prefix, _, ok := splitSheetRange(rangeVal); ok && sheetID != "" && prefix != sheetID {
-		return common.FlagErrorf("--range prefix %q does not match --sheet-id %q", prefix, sheetID)
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--range prefix %q does not match --sheet-id %q", prefix, sheetID).WithParam("--range")
 	}
 	return nil
 }
@@ -206,7 +206,7 @@ func validateFloatImageUpdatePayload(runtime *common.RuntimeContext) error {
 		runtime.Cmd.Flags().Changed("offset-x") ||
 		runtime.Cmd.Flags().Changed("offset-y")
 	if !hasField {
-		return common.FlagErrorf("specify at least one of --range, --width, --height, --offset-x, --offset-y to update")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --range, --width, --height, --offset-x, --offset-y to update")
 	}
 	return nil
 }
@@ -214,22 +214,22 @@ func validateFloatImageUpdatePayload(runtime *common.RuntimeContext) error {
 func validateFloatImageDims(runtime *common.RuntimeContext) error {
 	if runtime.Cmd.Flags().Changed("width") {
 		if v := runtime.Int("width"); v < 20 {
-			return common.FlagErrorf("--width must be >= 20 pixels, got %d", v)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--width must be >= 20 pixels, got %d", v).WithParam("--width")
 		}
 	}
 	if runtime.Cmd.Flags().Changed("height") {
 		if v := runtime.Int("height"); v < 20 {
-			return common.FlagErrorf("--height must be >= 20 pixels, got %d", v)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--height must be >= 20 pixels, got %d", v).WithParam("--height")
 		}
 	}
 	if runtime.Cmd.Flags().Changed("offset-x") {
 		if v := runtime.Int("offset-x"); v < 0 {
-			return common.FlagErrorf("--offset-x must be >= 0, got %d", v)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--offset-x must be >= 0, got %d", v).WithParam("--offset-x")
 		}
 	}
 	if runtime.Cmd.Flags().Changed("offset-y") {
 		if v := runtime.Int("offset-y"); v < 0 {
-			return common.FlagErrorf("--offset-y must be >= 0, got %d", v)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--offset-y must be >= 0, got %d", v).WithParam("--offset-y")
 		}
 	}
 	return nil
@@ -304,7 +304,7 @@ var SheetCreateFloatImage = common.Shortcut{
 		if s := runtime.Str("float-image-id"); s != "" {
 			body["float_image_id"] = s
 		}
-		data, err := runtime.CallAPI("POST", floatImageBasePath(token, runtime.Str("sheet-id")), nil, body)
+		data, err := runtime.CallAPITyped("POST", floatImageBasePath(token, runtime.Str("sheet-id")), nil, body)
 		if err != nil {
 			return err
 		}
@@ -353,7 +353,7 @@ var SheetUpdateFloatImage = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFloatImageToken(runtime)
 		body := buildFloatImageBody(runtime, false)
-		data, err := runtime.CallAPI("PATCH", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, body)
+		data, err := runtime.CallAPITyped("PATCH", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, body)
 		if err != nil {
 			return err
 		}
@@ -387,7 +387,7 @@ var SheetGetFloatImage = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFloatImageToken(runtime)
-		data, err := runtime.CallAPI("GET", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, nil)
+		data, err := runtime.CallAPITyped("GET", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, nil)
 		if err != nil {
 			return err
 		}
@@ -420,7 +420,7 @@ var SheetListFloatImages = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFloatImageToken(runtime)
-		data, err := runtime.CallAPI("GET", floatImageBasePath(token, runtime.Str("sheet-id"))+"/query", nil, nil)
+		data, err := runtime.CallAPITyped("GET", floatImageBasePath(token, runtime.Str("sheet-id"))+"/query", nil, nil)
 		if err != nil {
 			return err
 		}
@@ -454,7 +454,7 @@ var SheetDeleteFloatImage = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateFloatImageToken(runtime)
-		data, err := runtime.CallAPI("DELETE", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, nil)
+		data, err := runtime.CallAPITyped("DELETE", floatImageItemPath(token, runtime.Str("sheet-id"), runtime.Str("float-image-id")), nil, nil)
 		if err != nil {
 			return err
 		}

shortcuts/sheets/backward/lark_sheets_row_column_management.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -31,7 +32,7 @@ var SheetAddDimension = common.Shortcut{
 		}
 		length := runtime.Int("length")
 		if length < 1 || length > 5000 {
-			return common.FlagErrorf("--length must be between 1 and 5000, got %d", length)
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--length must be between 1 and 5000, got %d", length).WithParam("--length")
 		}
 		return nil
 	},
@@ -51,7 +52,7 @@ var SheetAddDimension = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateSheetManageToken(runtime)
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/dimension_range", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{
@@ -91,10 +92,10 @@ var SheetInsertDimension = common.Shortcut{
 			return err
 		}
 		if runtime.Int("start-index") < 0 {
-			return common.FlagErrorf("--start-index must be >= 0")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-index must be >= 0").WithParam("--start-index")
 		}
 		if runtime.Int("end-index") <= runtime.Int("start-index") {
-			return common.FlagErrorf("--end-index must be greater than --start-index")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-index must be greater than --start-index").WithParam("--end-index")
 		}
 		return nil
 	},
@@ -131,7 +132,7 @@ var SheetInsertDimension = common.Shortcut{
 			body["inheritStyle"] = s
 		}
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/insert_dimension_range", validate.EncodePathSegment(token)),
 			nil, body,
 		)
@@ -165,16 +166,16 @@ var SheetUpdateDimension = common.Shortcut{
 			return err
 		}
 		if runtime.Int("start-index") < 1 {
-			return common.FlagErrorf("--start-index must be >= 1")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-index must be >= 1").WithParam("--start-index")
 		}
 		if runtime.Int("end-index") < runtime.Int("start-index") {
-			return common.FlagErrorf("--end-index must be >= --start-index")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-index must be >= --start-index").WithParam("--end-index")
 		}
 		if !runtime.Cmd.Flags().Changed("visible") && !runtime.Cmd.Flags().Changed("fixed-size") {
-			return common.FlagErrorf("specify at least one of --visible or --fixed-size")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --visible or --fixed-size")
 		}
 		if runtime.Cmd.Flags().Changed("fixed-size") && runtime.Int("fixed-size") < 1 {
-			return common.FlagErrorf("--fixed-size must be >= 1")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--fixed-size must be >= 1").WithParam("--fixed-size")
 		}
 		return nil
 	},
@@ -211,7 +212,7 @@ var SheetUpdateDimension = common.Shortcut{
 			props["fixedSize"] = runtime.Int("fixed-size")
 		}
 
-		data, err := runtime.CallAPI("PUT",
+		data, err := runtime.CallAPITyped("PUT",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/dimension_range", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{
@@ -253,13 +254,13 @@ var SheetMoveDimension = common.Shortcut{
 			return err
 		}
 		if runtime.Int("start-index") < 0 {
-			return common.FlagErrorf("--start-index must be >= 0")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-index must be >= 0").WithParam("--start-index")
 		}
 		if runtime.Int("end-index") < runtime.Int("start-index") {
-			return common.FlagErrorf("--end-index must be >= --start-index")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-index must be >= --start-index").WithParam("--end-index")
 		}
 		if runtime.Int("destination-index") < 0 {
-			return common.FlagErrorf("--destination-index must be >= 0")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--destination-index must be >= 0").WithParam("--destination-index")
 		}
 		return nil
 	},
@@ -281,7 +282,7 @@ var SheetMoveDimension = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateSheetManageToken(runtime)
 
-		data, err := runtime.CallAPI("POST",
+		data, err := runtime.CallAPITyped("POST",
 			fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/%s/move_dimension",
 				validate.EncodePathSegment(token),
 				validate.EncodePathSegment(runtime.Str("sheet-id")),
@@ -324,10 +325,10 @@ var SheetDeleteDimension = common.Shortcut{
 			return err
 		}
 		if runtime.Int("start-index") < 1 {
-			return common.FlagErrorf("--start-index must be >= 1")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-index must be >= 1").WithParam("--start-index")
 		}
 		if runtime.Int("end-index") < runtime.Int("start-index") {
-			return common.FlagErrorf("--end-index must be >= --start-index")
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-index must be >= --start-index").WithParam("--end-index")
 		}
 		return nil
 	},
@@ -348,7 +349,7 @@ var SheetDeleteDimension = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		token, _ := validateSheetManageToken(runtime)
 
-		data, err := runtime.CallAPI("DELETE",
+		data, err := runtime.CallAPITyped("DELETE",
 			fmt.Sprintf("/open-apis/sheets/v2/spreadsheets/%s/dimension_range", validate.EncodePathSegment(token)),
 			nil,
 			map[string]interface{}{