fix: update sheets filter view condition validation

docs: document block anchor URLs in lark-doc skill (#1120 )
feat(schema): output json spec envelope for all API commands (#1048 )
2026-07-04 23:15:25 +08:00 · 2026-05-27 17:31:19 +08:00 · 2026-05-27 14:32:46 +08:00 · 2026-05-27 12:04:01 +08:00 · 2026-05-26 22:17:54 +08:00 · 2026-05-26 22:06:12 +08:00
46 changed files with 4857 additions and 208 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
 # Build output
-/lark-cli
+/lark-cli*
 .cache/
 dist/
 bin/
--- a/cmd/schema/schema.go
+++ b/cmd/schema/schema.go
@@ -14,6 +14,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/schema"
 	"github.com/larksuite/cli/internal/util"
 	"github.com/spf13/cobra"
 )
@@ -24,7 +25,8 @@ type SchemaOptions struct {
 	Ctx     context.Context

 	// Positional args
-	Path string
+	Path      string   // first positional, when only one is given
+	ExtraArgs []string // 2nd+ positional args (space-separated form)

 	// Flags
 	Format string
@@ -359,13 +361,16 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	opts := &SchemaOptions{Factory: f}

 	cmd := &cobra.Command{
-		Use:   "schema [path]",
+		Use:   "schema [path | service resource method]",
 		Short: "View API method parameters, types, and scopes",
-		Args:  cobra.MaximumNArgs(1),
+		Args:  cobra.MaximumNArgs(8),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) > 0 {
 				opts.Path = args[0]
 			}
+			if len(args) > 1 {
+				opts.ExtraArgs = args[1:]
+			}
 			opts.Ctx = cmd.Context()
 			if runF != nil {
 				return runF(opts)
@@ -380,60 +385,108 @@ func NewCmdSchema(f *cmdutil.Factory, runF func(*SchemaOptions) error) *cobra.Co
 	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 		return []string{"json", "pretty"}, cobra.ShellCompDirectiveNoFileComp
 	})
-	cmdutil.SetRisk(cmd, "read")
+	cmdutil.SetRisk(cmd, cmdutil.RiskRead)

 	return cmd
 }

 // completeSchemaPath provides tab-completion for the schema path argument.
-// It handles dotted resource names (e.g. app.table.fields) by iterating all
-// resources and classifying each as a prefix-match or fully-matched.
+// It handles both legacy dotted resource names (e.g. app.table.fields) and the
+// newer space-separated form (e.g. `schema im messages reply`).
 func completeSchemaPath(f *cmdutil.Factory) func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
 	return func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
-		if len(args) > 0 {
-			return nil, cobra.ShellCompDirectiveNoFileComp
-		}
+		mode := f.ResolveStrictMode(cmd.Context())

-		parts := strings.Split(toComplete, ".")
-
-		// Level 1: complete service names
-		if len(parts) <= 1 {
-			var completions []string
-			for _, s := range registry.ListFromMetaProjects() {
-				if strings.HasPrefix(s, toComplete) {
-					completions = append(completions, s+".")
+		// Case 1: legacy "single dotted arg" path — no previous args yet
+		if len(args) == 0 {
+			parts := strings.Split(toComplete, ".")
+			if len(parts) <= 1 {
+				var completions []string
+				for _, s := range registry.ListFromMetaProjects() {
+					if strings.HasPrefix(s, toComplete) {
+						completions = append(completions, s+".")
+					}
+				}
+				return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+			}
+			serviceName := parts[0]
+			spec := registry.LoadFromMeta(serviceName)
+			if spec == nil {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			}
+			spec = filterSpecByStrictMode(spec, mode)
+			resources, _ := spec["resources"].(map[string]interface{})
+			if resources == nil {
+				return nil, cobra.ShellCompDirectiveNoFileComp
+			}
+			afterService := strings.Join(parts[1:], ".")
+			completions := completeSchemaPathForSpec(serviceName, resources, afterService)
+			allTrailingDot := len(completions) > 0
+			for _, c := range completions {
+				if !strings.HasSuffix(c, ".") {
+					allTrailingDot = false
+					break
 				}
 			}
-			return completions, cobra.ShellCompDirectiveNoFileComp | cobra.ShellCompDirectiveNoSpace
+			directive := cobra.ShellCompDirectiveNoFileComp
+			if allTrailingDot {
+				directive |= cobra.ShellCompDirectiveNoSpace
+			}
+			return completions, directive
 		}

-		serviceName := parts[0]
+		// Case 2: space-form, args already has segments
+		// Walk down service -> resource(s) -> method based on existing args
+		serviceName := args[0]
 		spec := registry.LoadFromMeta(serviceName)
 		if spec == nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}
-		mode := f.ResolveStrictMode(cmd.Context())
 		spec = filterSpecByStrictMode(spec, mode)
 		resources, _ := spec["resources"].(map[string]interface{})
 		if resources == nil {
 			return nil, cobra.ShellCompDirectiveNoFileComp
 		}

-		afterService := strings.Join(parts[1:], ".")
-		completions := completeSchemaPathForSpec(serviceName, resources, afterService)
-
-		allTrailingDot := len(completions) > 0
-		for _, c := range completions {
-			if !strings.HasSuffix(c, ".") {
-				allTrailingDot = false
-				break
+		// args[1:] are resource path segments (possibly partial); current
+		// toComplete is the next segment under cursor.
+		consumed := args[1:]
+		resource, _, remaining := findResourceByPath(resources, consumed)
+		if resource == nil {
+			// Suggest top-level resource names that match toComplete
+			var completions []string
+			for resName := range resources {
+				if strings.HasPrefix(resName, toComplete) {
+					completions = append(completions, resName)
+				}
+			}
+			sort.Strings(completions)
+			return completions, cobra.ShellCompDirectiveNoFileComp
+		}
+		if len(remaining) > 0 {
+			// Already typed past the resource — suggest methods
+			methods, _ := resource["methods"].(map[string]interface{})
+			methods = filterMethodsByStrictMode(methods, mode)
+			var completions []string
+			for mName := range methods {
+				if strings.HasPrefix(mName, toComplete) {
+					completions = append(completions, mName)
+				}
+			}
+			sort.Strings(completions)
+			return completions, cobra.ShellCompDirectiveNoFileComp
+		}
+		// Resource matched exactly, suggest methods
+		methods, _ := resource["methods"].(map[string]interface{})
+		methods = filterMethodsByStrictMode(methods, mode)
+		var completions []string
+		for mName := range methods {
+			if strings.HasPrefix(mName, toComplete) {
+				completions = append(completions, mName)
 			}
 		}
-		directive := cobra.ShellCompDirectiveNoFileComp
-		if allTrailingDot {
-			directive |= cobra.ShellCompDirectiveNoSpace
-		}
-		return completions, directive
+		sort.Strings(completions)
+		return completions, cobra.ShellCompDirectiveNoFileComp
 	}
 }

@@ -469,94 +522,231 @@ func schemaRun(opts *SchemaOptions) error {
 	out := opts.Factory.IOStreams.Out
 	mode := opts.Factory.ResolveStrictMode(opts.Ctx)

-	if opts.Path == "" {
-		printServices(out)
-		return nil
+	// args may have arrived as a single string (legacy single-arg path) or
+	// split into multiple — normalize to a single args slice.
+	var rawArgs []string
+	if opts.Path != "" {
+		rawArgs = []string{opts.Path}
 	}
-
-	parts := strings.Split(opts.Path, ".")
-
-	serviceName := parts[0]
-	spec := registry.LoadFromMeta(serviceName)
-	if spec == nil {
-		return output.ErrWithHint(output.ExitValidation, "validation",
-			fmt.Sprintf("Unknown service: %s", serviceName),
-			fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
-	}
-
-	if len(parts) == 1 {
-		if opts.Format == "pretty" {
-			printResourceList(out, spec, mode)
+	if len(opts.ExtraArgs) > 0 {
+		if opts.Path != "" {
+			rawArgs = append([]string{opts.Path}, opts.ExtraArgs...)
 		} else {
-			output.PrintJson(out, filterSpecByStrictMode(spec, mode))
+			rawArgs = append([]string(nil), opts.ExtraArgs...)
 		}
-		return nil
 	}
+	parts := schema.ParsePath(rawArgs)

+	if opts.Format == "pretty" {
+		return runPrettyMode(out, parts, mode)
+	}
+	return runJSONMode(out, parts, mode)
+}
+
+// runJSONMode dispatches list/single envelope output based on parts.
+// JSON mode uses embedded data only (bypasses remote overlay) so envelope
+// output is deterministic across machines.
+func runJSONMode(out io.Writer, parts []string, mode core.StrictMode) error {
+	filter := strictModeFilter(mode)
+
+	switch len(parts) {
+	case 0:
+		envs := schema.AssembleAll(filter)
+		output.PrintJson(out, envs)
+		return nil
+	case 1:
+		spec := registry.EmbeddedSpec(parts[0])
+		if spec == nil {
+			return errUnknownEmbeddedService(parts[0])
+		}
+		envs := schema.AssembleService(parts[0], spec, filter)
+		output.PrintJson(out, envs)
+		return nil
+	default:
+		return runJSONForPath(out, parts, filter)
+	}
+}
+
+// runJSONForPath handles len(parts) >= 2: try resource match first, fallback
+// to single-method match. Uses embedded data only.
+func runJSONForPath(out io.Writer, parts []string, filter schema.MethodFilter) error {
+	serviceName := parts[0]
+	spec := registry.EmbeddedSpec(serviceName)
+	if spec == nil {
+		return errUnknownEmbeddedService(serviceName)
+	}
 	resources, _ := spec["resources"].(map[string]interface{})
 	resource, resName, remaining := findResourceByPath(resources, parts[1:])
 	if resource == nil {
-		var resNames []string
+		var names []string
 		for k := range resources {
-			resNames = append(resNames, k)
+			names = append(names, k)
 		}
+		sort.Strings(names)
 		return output.ErrWithHint(output.ExitValidation, "validation",
 			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
-			fmt.Sprintf("Available: %s", strings.Join(resNames, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
 	}
-
 	if len(remaining) == 0 {
-		if opts.Format == "pretty" {
-			fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
-			methods, _ := resource["methods"].(map[string]interface{})
-			methods = filterMethodsByStrictMode(methods, mode)
-			for _, mName := range sortedKeys(methods) {
-				m, _ := methods[mName].(map[string]interface{})
-				httpMethod := registry.GetStrFromMap(m, "httpMethod")
-				desc := registry.GetStrFromMap(m, "description")
-				fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
-			}
-			fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
-		} else {
-			// For JSON output, filter methods in a copy to avoid mutating the registry.
-			if mode.IsActive() {
-				filtered := make(map[string]interface{})
-				for k, v := range resource {
-					filtered[k] = v
-				}
-				if methods, ok := resource["methods"].(map[string]interface{}); ok {
-					filtered["methods"] = filterMethodsByStrictMode(methods, mode)
-				}
-				output.PrintJson(out, filtered)
-			} else {
-				output.PrintJson(out, resource)
-			}
-		}
+		// Resource-scoped envelope array
+		envs := assembleResource(serviceName, resName, resource, filter)
+		output.PrintJson(out, envs)
 		return nil
 	}
+	methodName := remaining[0]
+	methods, _ := resource["methods"].(map[string]interface{})
+	method, ok := methods[methodName].(map[string]interface{})
+	if !ok {
+		var names []string
+		for k := range methods {
+			names = append(names, k)
+		}
+		sort.Strings(names)
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
+	}
+	if len(remaining) > 1 {
+		// Method exists but caller appended extra segments — reject so they
+		// don't silently get this method's schema when they typo'd the path.
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown path: %s.%s.%s",
+				serviceName, resName, strings.Join(remaining, ".")),
+			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
+				methodName, strings.Join(remaining[1:], ".")))
+	}
+	if filter != nil && !filter(method) {
+		// Method exists in spec but filtered out by strict mode
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Method %s.%s.%s not available in current identity mode", serviceName, resName, methodName),
+			"Use --as user / --as bot to switch")
+	}
+	env := schema.AssembleEnvelope(serviceName, []string{resName}, methodName, method)
+	output.PrintJson(out, env)
+	return nil
+}

+func assembleResource(serviceName, resName string, resource map[string]interface{}, filter schema.MethodFilter) []schema.Envelope {
+	methods, _ := resource["methods"].(map[string]interface{})
+	resourcePath := []string{resName}
+	var envs []schema.Envelope
+	for methodName, raw := range methods {
+		method, ok := raw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		if filter != nil && !filter(method) {
+			continue
+		}
+		envs = append(envs, schema.AssembleEnvelope(serviceName, resourcePath, methodName, method))
+	}
+	sort.Slice(envs, func(i, j int) bool { return envs[i].Name < envs[j].Name })
+	return envs
+}
+
+// runPrettyMode preserves the existing legacy pretty rendering verbatim.
+// All printServices/printResourceList/printMethodDetail calls stay unchanged.
+func runPrettyMode(out io.Writer, parts []string, mode core.StrictMode) error {
+	if len(parts) == 0 {
+		printServices(out)
+		return nil
+	}
+	serviceName := parts[0]
+	spec := registry.LoadFromMeta(serviceName)
+	if spec == nil {
+		return errUnknownService(serviceName)
+	}
+	if len(parts) == 1 {
+		printResourceList(out, spec, mode)
+		return nil
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	resource, resName, remaining := findResourceByPath(resources, parts[1:])
+	if resource == nil {
+		var names []string
+		for k := range resources {
+			names = append(names, k)
+		}
+		sort.Strings(names)
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown resource: %s.%s", serviceName, strings.Join(parts[1:], ".")),
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
+	}
+	if len(remaining) == 0 {
+		fmt.Fprintf(out, "%s%s.%s%s\n\n", output.Bold, serviceName, resName, output.Reset)
+		methods, _ := resource["methods"].(map[string]interface{})
+		methods = filterMethodsByStrictMode(methods, mode)
+		for _, mName := range sortedKeys(methods) {
+			m, _ := methods[mName].(map[string]interface{})
+			httpMethod := registry.GetStrFromMap(m, "httpMethod")
+			desc := registry.GetStrFromMap(m, "description")
+			fmt.Fprintf(out, "  %-7s %s%s%s  %s%s%s\n", httpMethod, output.Bold, mName, output.Reset, output.Dim, desc, output.Reset)
+		}
+		fmt.Fprintf(out, "\n%sUsage: lark-cli schema %s.%s.<method>%s\n", output.Dim, serviceName, resName, output.Reset)
+		return nil
+	}
 	methodName := remaining[0]
 	methods, _ := resource["methods"].(map[string]interface{})
 	methods = filterMethodsByStrictMode(methods, mode)
 	method, ok := methods[methodName].(map[string]interface{})
 	if !ok {
-		var mNames []string
+		var names []string
 		for k := range methods {
-			mNames = append(mNames, k)
+			names = append(names, k)
 		}
+		sort.Strings(names)
 		return output.ErrWithHint(output.ExitValidation, "validation",
 			fmt.Sprintf("Unknown method: %s.%s.%s", serviceName, resName, methodName),
-			fmt.Sprintf("Available: %s", strings.Join(mNames, ", ")))
+			fmt.Sprintf("Available: %s", strings.Join(names, ", ")))
 	}
-
-	if opts.Format == "pretty" {
-		printMethodDetail(out, spec, resName, methodName, method)
-	} else {
-		output.PrintJson(out, method)
+	if len(remaining) > 1 {
+		return output.ErrWithHint(output.ExitValidation, "validation",
+			fmt.Sprintf("Unknown path: %s.%s.%s",
+				serviceName, resName, strings.Join(remaining, ".")),
+			fmt.Sprintf("Method %q exists but the trailing segments %q do not resolve",
+				methodName, strings.Join(remaining[1:], ".")))
 	}
+	printMethodDetail(out, spec, resName, methodName, method)
 	return nil
 }

+// strictModeFilter adapts core.StrictMode into a schema.MethodFilter, or returns
+// nil if strict mode is not active.
+func strictModeFilter(mode core.StrictMode) schema.MethodFilter {
+	if !mode.IsActive() {
+		return nil
+	}
+	token := registry.IdentityToAccessToken(string(mode.ForcedIdentity()))
+	return func(method map[string]interface{}) bool {
+		tokens, _ := method["accessTokens"].([]interface{})
+		if tokens == nil {
+			return true // permissive when meta_data lacks accessTokens
+		}
+		for _, t := range tokens {
+			if s, _ := t.(string); s == token {
+				return true
+			}
+		}
+		return false
+	}
+}
+
+func errUnknownService(name string) error {
+	return output.ErrWithHint(output.ExitValidation, "validation",
+		fmt.Sprintf("Unknown service: %s", name),
+		fmt.Sprintf("Available: %s", strings.Join(registry.ListFromMetaProjects(), ", ")))
+}
+
+// errUnknownEmbeddedService is the JSON-mode variant: it lists only embedded
+// services (no overlay) because JSON mode itself bypasses overlay; suggesting
+// overlay-only services would mislead callers when those services subsequently
+// fail to resolve in envelope output.
+func errUnknownEmbeddedService(name string) error {
+	return output.ErrWithHint(output.ExitValidation, "validation",
+		fmt.Sprintf("Unknown service: %s", name),
+		fmt.Sprintf("Available: %s", strings.Join(registry.EmbeddedServiceNames(), ", ")))
+}
+
 // filterSpecByStrictMode returns a shallow copy of spec with each resource's methods
 // filtered by strict mode. Returns the original spec when strict mode is off.
 func filterSpecByStrictMode(spec map[string]interface{}, mode core.StrictMode) map[string]interface{} {
--- a/cmd/schema/schema_test.go
+++ b/cmd/schema/schema_test.go
@@ -5,6 +5,7 @@ package schema

 import (
 	"bytes"
+	"encoding/json"
 	"strings"
 	"testing"

@@ -33,17 +34,165 @@ func TestSchemaCmd_FlagParsing(t *testing.T) {
 	}
 }

-func TestSchemaCmd_NoArgs(t *testing.T) {
+func TestSchemaCmd_NoArgs_Pretty(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, nil)

 	cmd := NewCmdSchema(f, nil)
-	cmd.SetArgs([]string{})
-	err := cmd.Execute()
-	if err != nil {
+	cmd.SetArgs([]string{"--format", "pretty"})
+	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	if !strings.Contains(stdout.String(), "Available services") {
-		t.Error("expected service list output")
+		t.Error("expected service list in pretty mode")
+	}
+}
+
+func TestSchemaCmd_NoArgs_JSON_IsArray(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{}) // default --format json
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := strings.TrimSpace(stdout.String())
+	if !strings.HasPrefix(out, "[") {
+		head := out
+		if len(head) > 80 {
+			head = head[:80]
+		}
+		t.Errorf("expected JSON array root, first 80 chars:\n%s", head)
+	}
+	var envs []map[string]interface{}
+	if err := json.Unmarshal([]byte(out), &envs); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if len(envs) < 193 {
+		t.Errorf("envelopes count = %d, want >= 193", len(envs))
+	}
+}
+
+func TestSchemaCmd_JSONIsEnvelope(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.images.create", "--format", "json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("not valid JSON: %v\n%s", err, stdout.String())
+	}
+	if env["name"] != "im images create" {
+		t.Errorf("name = %v, want \"im images create\"", env["name"])
+	}
+	for _, key := range []string{"description", "inputSchema", "outputSchema", "_meta"} {
+		if _, ok := env[key]; !ok {
+			t.Errorf("missing top-level key: %s", key)
+		}
+	}
+	meta, _ := env["_meta"].(map[string]interface{})
+	if meta["envelope_version"] != "1.0" {
+		t.Errorf("envelope_version = %v, want \"1.0\"", meta["envelope_version"])
+	}
+}
+
+func TestSchemaCmd_SpaceSeparatedPath_EqualsDotted(t *testing.T) {
+	f1, out1, _, _ := cmdutil.TestFactory(t, nil)
+	cmd1 := NewCmdSchema(f1, nil)
+	cmd1.SetArgs([]string{"im", "images", "create"})
+	if err := cmd1.Execute(); err != nil {
+		t.Fatalf("space form failed: %v", err)
+	}
+
+	f2, out2, _, _ := cmdutil.TestFactory(t, nil)
+	cmd2 := NewCmdSchema(f2, nil)
+	cmd2.SetArgs([]string{"im.images.create"})
+	if err := cmd2.Execute(); err != nil {
+		t.Fatalf("dotted form failed: %v", err)
+	}
+
+	if out1.String() != out2.String() {
+		t.Errorf("space and dotted forms produced different output")
+	}
+}
+
+func TestSchemaCmd_ServiceListIsArray(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var envs []map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envs); err != nil {
+		t.Fatalf("unmarshal failed: %v\n%s", err, stdout.String())
+	}
+	if len(envs) == 0 {
+		t.Fatal("expected non-empty array for service im")
+	}
+	for _, e := range envs {
+		name, _ := e["name"].(string)
+		if !strings.HasPrefix(name, "im ") {
+			t.Errorf("envelope name %q does not start with \"im \"", name)
+		}
+	}
+}
+
+func TestSchemaCmd_HighRiskYesInjection(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.messages.delete"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	is, _ := env["inputSchema"].(map[string]interface{})
+	props, _ := is["properties"].(map[string]interface{})
+	if _, ok := props["yes"]; !ok {
+		t.Errorf("inputSchema.properties.yes missing for high-risk-write command")
+	}
+}
+
+func TestSchemaCmd_NoYesForReadRisk(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.reactions.list"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var env map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	is, _ := env["inputSchema"].(map[string]interface{})
+	props, _ := is["properties"].(map[string]interface{})
+	if _, ok := props["yes"]; ok {
+		t.Errorf("yes property should not appear for risk=read command")
+	}
+}
+
+func TestSchemaCmd_PrettyUnchanged_KeyTextPresent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, nil)
+
+	cmd := NewCmdSchema(f, nil)
+	cmd.SetArgs([]string{"im.images.create", "--format", "pretty"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	// Existing pretty rendering surfaces these markers — they must still appear
+	for _, want := range []string{"Parameters:", "Response:", "Identity:", "Scopes:", "CLI:"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("pretty output missing marker %q", want)
+		}
 	}
 }

--- a/events/minutes/minute_generated.go
+++ b/events/minutes/minute_generated.go
@@ -0,0 +1,116 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+const (
+	minutesDetailRetryDelay = 500 * time.Millisecond
+	minutesDetailMaxRetries = 2
+)
+
+// MinutesMinuteSourceOutput is the flattened minute source payload.
+type MinutesMinuteSourceOutput struct {
+	SourceType     string `json:"source_type,omitempty"      desc:"Minute source type"`
+	SourceEntityID string `json:"source_entity_id,omitempty" desc:"Source entity ID"`
+}
+
+// MinutesMinuteGeneratedOutput is the flattened shape for minutes.minute.generated_v1.
+type MinutesMinuteGeneratedOutput struct {
+	Type         string                     `json:"type"                     desc:"Event type; always minutes.minute.generated_v1"`
+	EventID      string                     `json:"event_id,omitempty"       desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp    string                     `json:"timestamp,omitempty"      desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
+	MinuteToken  string                     `json:"minute_token,omitempty"   desc:"Minute token"`
+	Title        string                     `json:"title,omitempty"          desc:"Minute title"`
+	MinuteSource *MinutesMinuteSourceOutput `json:"minute_source,omitempty"  desc:"Minute source metadata"`
+}
+
+func processMinutesMinuteGenerated(ctx context.Context, rt event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			MinuteToken  string `json:"minute_token"`
+			MinuteSource struct {
+				SourceType     string `json:"source_type"`
+				SourceEntityID string `json:"source_entity_id"`
+			} `json:"minute_source"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	out := &MinutesMinuteGeneratedOutput{
+		Type:        envelope.Header.EventType,
+		EventID:     envelope.Header.EventID,
+		Timestamp:   envelope.Header.CreateTime,
+		MinuteToken: envelope.Event.MinuteToken,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	if src := envelope.Event.MinuteSource; src.SourceType != "" || src.SourceEntityID != "" {
+		out.MinuteSource = &MinutesMinuteSourceOutput{
+			SourceType:     src.SourceType,
+			SourceEntityID: src.SourceEntityID,
+		}
+	}
+
+	if rt != nil && out.MinuteToken != "" {
+		fillMinutesMinuteGeneratedDetails(ctx, rt, out)
+	}
+
+	return json.Marshal(out)
+}
+
+func fillMinutesMinuteGeneratedDetails(ctx context.Context, rt event.APIClient, out *MinutesMinuteGeneratedOutput) {
+	if rt == nil || out == nil || out.MinuteToken == "" {
+		return
+	}
+
+	path := fmt.Sprintf(pathMinuteDetailFmt, validate.EncodePathSegment(out.MinuteToken))
+
+	type minuteDetailResp struct {
+		Data struct {
+			Minute struct {
+				Title string `json:"title"`
+			} `json:"minute"`
+		} `json:"data"`
+	}
+
+	for attempt := 0; attempt <= minutesDetailMaxRetries; attempt++ {
+		if attempt > 0 {
+			time.Sleep(minutesDetailRetryDelay)
+		}
+
+		raw, err := rt.CallAPI(ctx, "GET", path, nil)
+		if err != nil {
+			continue
+		}
+
+		var resp minuteDetailResp
+		if err := json.Unmarshal(raw, &resp); err != nil {
+			continue
+		}
+
+		if resp.Data.Minute.Title == "" {
+			continue
+		}
+
+		out.Title = resp.Data.Minute.Title
+		return
+	}
+}
--- a/events/minutes/minute_generated_test.go
+++ b/events/minutes/minute_generated_test.go
@@ -0,0 +1,353 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+	"github.com/larksuite/cli/internal/validate"
+)
+
+type stubAPIClient struct {
+	callFn func(ctx context.Context, method, path string, body any) (json.RawMessage, error)
+}
+
+func (s *stubAPIClient) CallAPI(ctx context.Context, method, path string, body any) (json.RawMessage, error) {
+	if s.callFn == nil {
+		return nil, nil
+	}
+	return s.callFn(ctx, method, path, body)
+}
+
+func assertSubscriptionRequest(t *testing.T, gotBody any, wantEventType string) {
+	t.Helper()
+	want := map[string]string{"event_type": wantEventType}
+	if !reflect.DeepEqual(gotBody, want) {
+		t.Fatalf("request body = %#v, want %#v", gotBody, want)
+	}
+}
+
+func TestMain(m *testing.M) {
+	for _, k := range Keys() {
+		event.RegisterKey(k)
+	}
+	os.Exit(m.Run())
+}
+
+func TestMinutesKeys_ProcessedMinuteGeneratedRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMinuteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMinuteGenerated)
+	}
+	if def.Schema.Custom == nil {
+		t.Error("Processed key must set Schema.Custom")
+	}
+	if def.Schema.Native != nil {
+		t.Error("Processed key must not set Schema.Native")
+	}
+	if def.Process == nil {
+		t.Error("Process must not be nil for processed key")
+	}
+	if def.PreConsume == nil {
+		t.Error("PreConsume must not be nil for processed key")
+	}
+	if len(def.Scopes) != 1 || def.Scopes[0] != "minutes:minutes.basic:read" {
+		t.Errorf("Scopes = %v", def.Scopes)
+	}
+	if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v", def.AuthTypes)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	var gotMethod, gotPath string
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			gotMethod = method
+			gotPath = path
+			if body != nil {
+				t.Fatalf("GET detail body = %#v, want nil", body)
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"token": "<doc_token_001>",
+						"title": "产品周会的视频会议",
+						"note_id": "7616590025794260496"
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_001",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_001>",
+			"minute_source": {
+				"source_type": "meeting",
+				"source_entity_id": "6911188411934433028"
+			}
+		}
+	}`)
+
+	if gotMethod != "GET" {
+		t.Errorf("detail method = %q, want GET", gotMethod)
+	}
+	if gotPath != fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment("<doc_token_001>")) {
+		t.Errorf("detail path = %q", gotPath)
+	}
+	if out.Type != eventTypeMinuteGenerated {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_minute_001" || out.Timestamp != "1608725989000" {
+		t.Errorf("EventID/Timestamp = %q/%q", out.EventID, out.Timestamp)
+	}
+	if out.MinuteToken != "<doc_token_001>" {
+		t.Errorf("MinuteToken = %q", out.MinuteToken)
+	}
+	if out.Title != "产品周会的视频会议" {
+		t.Errorf("Title = %q", out.Title)
+	}
+	if out.MinuteSource == nil {
+		t.Fatal("MinuteSource should not be nil")
+	}
+	if out.MinuteSource.SourceType != "meeting" || out.MinuteSource.SourceEntityID != "6911188411934433028" {
+		t.Errorf("MinuteSource = %+v", out.MinuteSource)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_DetailFailureFallsBackToBaseFields(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			called++
+			return nil, context.DeadlineExceeded
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_002",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989001"
+		},
+		"event": {
+			"minute_token": "<doc_token_004>",
+			"minute_source": {
+				"source_type": "meeting",
+				"source_entity_id": "7641156270787481117"
+			}
+		}
+	}`)
+
+	wantCalls := 1 + minutesDetailMaxRetries
+	if called != wantCalls {
+		t.Fatalf("detail API called %d times, want %d", called, wantCalls)
+	}
+	if out.MinuteToken != "<doc_token_004>" {
+		t.Errorf("MinuteToken = %q", out.MinuteToken)
+	}
+	if out.Title != "" {
+		t.Errorf("Title = %q, want empty", out.Title)
+	}
+	if out.MinuteSource == nil {
+		t.Fatal("MinuteSource should remain from event payload")
+	}
+	if out.MinuteSource.SourceType != "meeting" || out.MinuteSource.SourceEntityID != "7641156270787481117" {
+		t.Errorf("MinuteSource = %+v", out.MinuteSource)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_EmptyTitleRetriesAndSucceeds(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			if called <= 1 {
+				return json.RawMessage(`{
+					"code": 0,
+					"msg": "success",
+					"data": {
+						"minute": {
+							"title": ""
+						}
+					}
+				}`), nil
+			}
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"title": "delayed title"
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_retry",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_003>"
+		}
+	}`)
+
+	if called != 2 {
+		t.Fatalf("detail API called %d times, want 2 (1 initial + 1 retry)", called)
+	}
+	if out.Title != "delayed title" {
+		t.Errorf("Title = %q, want delayed title", out.Title)
+	}
+}
+
+func TestProcessMinutesMinuteGenerated_EmptyTitleExhaustsRetries(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	called := 0
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, _, _ string, _ any) (json.RawMessage, error) {
+			called++
+			return json.RawMessage(`{
+				"code": 0,
+				"msg": "success",
+				"data": {
+					"minute": {
+						"title": ""
+					}
+				}
+			}`), nil
+		},
+	}
+
+	out := runMinuteGenerated(t, rt, `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_minute_exhaust",
+			"event_type": "minutes.minute.generated_v1",
+			"create_time": "1608725989000"
+		},
+		"event": {
+			"minute_token": "<doc_token_002>"
+		}
+	}`)
+
+	wantCalls := 1 + minutesDetailMaxRetries
+	if called != wantCalls {
+		t.Fatalf("detail API called %d times, want %d", called, wantCalls)
+	}
+	if out.Title != "" {
+		t.Errorf("Title = %q, want empty after exhausted retries", out.Title)
+	}
+}
+
+func TestMinutesMinuteGenerated_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMinuteGenerated)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMinuteGenerated)
+	}
+
+	type call struct {
+		method string
+		path   string
+		body   any
+	}
+	var calls []call
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			calls = append(calls, call{method: method, path: path, body: body})
+			return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+		},
+	}
+
+	cleanup, err := def.PreConsume(context.Background(), rt, nil)
+	if err != nil {
+		t.Fatalf("PreConsume error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatal("cleanup must not be nil")
+	}
+	if len(calls) != 1 {
+		t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+	}
+	if calls[0].method != "POST" || calls[0].path != pathMinuteSubscribe {
+		t.Fatalf("subscribe call = %+v", calls[0])
+	}
+	assertSubscriptionRequest(t, calls[0].body, eventTypeMinuteGenerated)
+
+	cleanup()
+	if len(calls) != 2 {
+		t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+	}
+	if calls[1].method != "POST" || calls[1].path != pathMinuteUnsubscribe {
+		t.Fatalf("unsubscribe call = %+v", calls[1])
+	}
+	assertSubscriptionRequest(t, calls[1].body, eventTypeMinuteGenerated)
+}
+
+func TestProcessMinutesMinuteGenerated_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	raw := &event.RawEvent{
+		EventType: eventTypeMinuteGenerated,
+		Payload:   json.RawMessage(`not json`),
+		Timestamp: time.Now(),
+	}
+	got, err := processMinutesMinuteGenerated(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process should swallow parse errors, got %v", err)
+	}
+	if string(got) != "not json" {
+		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+	}
+}
+
+func runMinuteGenerated(t *testing.T, rt event.APIClient, payload string) MinutesMinuteGeneratedOutput {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventTypeMinuteGenerated,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := processMinutesMinuteGenerated(context.Background(), rt, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	var out MinutesMinuteGeneratedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid MinutesMinuteGeneratedOutput JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}
--- a/events/minutes/preconsume.go
+++ b/events/minutes/preconsume.go
@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const cleanupTimeout = 5 * time.Second
+
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}
--- a/events/minutes/register.go
+++ b/events/minutes/register.go
@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package minutes registers Minutes-domain EventKeys.
+package minutes
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const (
+	eventTypeMinuteGenerated = "minutes.minute.generated_v1"
+
+	pathMinuteSubscribe   = "/open-apis/minutes/v1/minutes/subscription"
+	pathMinuteUnsubscribe = "/open-apis/minutes/v1/minutes/unsubscription"
+
+	pathMinuteDetailFmt = "/open-apis/minutes/v1/minutes/%s"
+)
+
+// Keys returns all Minutes-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeMinuteGenerated,
+			DisplayName: "Minute generated",
+			Description: "Triggered when a minute has been generated",
+			EventType:   eventTypeMinuteGenerated,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(MinutesMinuteGeneratedOutput{})},
+			},
+			Process:    processMinutesMinuteGenerated,
+			PreConsume: subscriptionPreConsume(eventTypeMinuteGenerated, pathMinuteSubscribe, pathMinuteUnsubscribe),
+			Scopes:     []string{"minutes:minutes.basic:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMinuteGenerated},
+		},
+	}
+}
--- a/events/register.go
+++ b/events/register.go
@@ -6,13 +6,17 @@ package events

 import (
 	"github.com/larksuite/cli/events/im"
+	"github.com/larksuite/cli/events/minutes"
+	"github.com/larksuite/cli/events/vc"
 	"github.com/larksuite/cli/internal/event"
 )

-// Mail is intentionally omitted: only IM is wired up this phase.
+// Mail is intentionally omitted in this phase.
 func init() {
 	all := [][]event.KeyDefinition{
 		im.Keys(),
+		minutes.Keys(),
+		vc.Keys(),
 	}
 	for _, keys := range all {
 		for _, k := range keys {
--- a/events/vc/participant_meeting_ended.go
+++ b/events/vc/participant_meeting_ended.go
@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"strconv"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+// VCParticipantMeetingEndedOutput is the flattened shape for vc.meeting.participant_meeting_ended_v1.
+type VCParticipantMeetingEndedOutput struct {
+	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_ended_v1"`
+	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
+	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present"                                                                 kind:"timestamp_ms"`
+	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID"                                                                                                                                                kind:"meeting_id"`
+	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
+	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
+	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
+	EndTime         string `json:"end_time,omitempty"        desc:"Meeting end time in RFC3339, converted to the local timezone"`
+	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
+}
+
+func processVCParticipantMeetingEnded(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
+	var envelope struct {
+		Header struct {
+			EventID    string `json:"event_id"`
+			EventType  string `json:"event_type"`
+			CreateTime string `json:"create_time"`
+		} `json:"header"`
+		Event struct {
+			Meeting struct {
+				ID              string `json:"id"`
+				Topic           string `json:"topic"`
+				MeetingNo       string `json:"meeting_no"`
+				StartTime       string `json:"start_time"`
+				EndTime         string `json:"end_time"`
+				CalendarEventID string `json:"calendar_event_id"`
+			} `json:"meeting"`
+		} `json:"event"`
+	}
+	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
+		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
+	}
+
+	meeting := envelope.Event.Meeting
+	out := &VCParticipantMeetingEndedOutput{
+		Type:            envelope.Header.EventType,
+		EventID:         envelope.Header.EventID,
+		Timestamp:       envelope.Header.CreateTime,
+		MeetingID:       meeting.ID,
+		Topic:           meeting.Topic,
+		MeetingNo:       meeting.MeetingNo,
+		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
+		EndTime:         unixSecondsToLocalRFC3339(meeting.EndTime),
+		CalendarEventID: meeting.CalendarEventID,
+	}
+	if out.Type == "" {
+		out.Type = raw.EventType
+	}
+	return json.Marshal(out)
+}
+
+func unixSecondsToLocalRFC3339(raw string) string {
+	if raw == "" {
+		return ""
+	}
+	secs, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil {
+		return ""
+	}
+	return time.Unix(secs, 0).Local().Format(time.RFC3339)
+}
--- a/events/vc/participant_meeting_ended_test.go
+++ b/events/vc/participant_meeting_ended_test.go
@@ -0,0 +1,203 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+func TestMain(m *testing.M) {
+	for _, k := range Keys() {
+		event.RegisterKey(k)
+	}
+	os.Exit(m.Run())
+}
+
+func TestVCKeys_ProcessedMeetingEndedRegistered(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup(eventTypeMeetingEnded)
+	if !ok {
+		t.Fatalf("%s should be registered via Keys()", eventTypeMeetingEnded)
+	}
+	if def.Schema.Custom == nil {
+		t.Error("Processed key must set Schema.Custom")
+	}
+	if def.Schema.Native != nil {
+		t.Error("Processed key must not set Schema.Native")
+	}
+	if def.Process == nil {
+		t.Error("Process must not be nil for processed key")
+	}
+	if def.PreConsume == nil {
+		t.Error("PreConsume must not be nil for processed key")
+	}
+	if len(def.Scopes) != 1 || def.Scopes[0] != "vc:meeting.meetingevent:read" {
+		t.Errorf("Scopes = %v", def.Scopes)
+	}
+	if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
+		t.Errorf("AuthTypes = %v", def.AuthTypes)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	payload := `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_end_001",
+			"event_type": "vc.meeting.participant_meeting_ended_v1",
+			"create_time": "1608725989000",
+			"app_id": "cli_test"
+		},
+		"event": {
+			"meeting": {
+				"id": "6911188411934433028",
+				"topic": "my meeting",
+				"meeting_no": "235812466",
+				"start_time": "1608883322",
+				"end_time": "1608883899",
+				"calendar_event_id": "efa67a98-06a8-4df5-8559-746c8f4477ef_0"
+			}
+		}
+	}`
+	out := runMeetingEnded(t, payload)
+
+	if out.Type != eventTypeMeetingEnded {
+		t.Errorf("Type = %q", out.Type)
+	}
+	if out.EventID != "ev_vc_end_001" {
+		t.Errorf("EventID = %q", out.EventID)
+	}
+	if out.Timestamp != "1608725989000" {
+		t.Errorf("Timestamp = %q", out.Timestamp)
+	}
+	if out.MeetingID != "6911188411934433028" {
+		t.Errorf("MeetingID = %q", out.MeetingID)
+	}
+	if out.Topic != "my meeting" || out.MeetingNo != "235812466" {
+		t.Errorf("Topic/MeetingNo = %q/%q", out.Topic, out.MeetingNo)
+	}
+	if out.CalendarEventID != "efa67a98-06a8-4df5-8559-746c8f4477ef_0" {
+		t.Errorf("CalendarEventID = %q", out.CalendarEventID)
+	}
+	if want := time.Unix(1608883322, 0).Local().Format(time.RFC3339); out.StartTime != want {
+		t.Errorf("StartTime = %q, want %q", out.StartTime, want)
+	}
+	if want := time.Unix(1608883899, 0).Local().Format(time.RFC3339); out.EndTime != want {
+		t.Errorf("EndTime = %q, want %q", out.EndTime, want)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded_InvalidMeetingTimes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	payload := `{
+		"schema": "2.0",
+		"header": {
+			"event_id": "ev_vc_end_002",
+			"event_type": "vc.meeting.participant_meeting_ended_v1",
+			"create_time": "1608725989001"
+		},
+		"event": {
+			"meeting": {
+				"id": "meeting_invalid_time",
+				"start_time": "bad",
+				"end_time": ""
+			}
+		}
+	}`
+	out := runMeetingEnded(t, payload)
+	if out.StartTime != "" || out.EndTime != "" {
+		t.Errorf("StartTime/EndTime = %q/%q, want empty strings", out.StartTime, out.EndTime)
+	}
+}
+
+func TestProcessVCParticipantMeetingEnded_MalformedPayload(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	raw := &event.RawEvent{
+		EventType: eventTypeMeetingEnded,
+		Payload:   json.RawMessage(`not json`),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCParticipantMeetingEnded(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process should swallow parse errors, got %v", err)
+	}
+	if string(got) != "not json" {
+		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
+	}
+}
+
+func TestVCParticipantMeetingEnded_PreConsumeSubscriptionLifecycle(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	def, ok := event.Lookup("vc.meeting.participant_meeting_ended_v1")
+	if !ok {
+		t.Fatal("vc.meeting.participant_meeting_ended_v1 should be registered via Keys()")
+	}
+
+	type call struct {
+		method string
+		path   string
+		body   any
+	}
+	var calls []call
+	rt := &stubAPIClient{
+		callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
+			calls = append(calls, call{method: method, path: path, body: body})
+			return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
+		},
+	}
+
+	cleanup, err := def.PreConsume(context.Background(), rt, nil)
+	if err != nil {
+		t.Fatalf("PreConsume error: %v", err)
+	}
+	if cleanup == nil {
+		t.Fatal("cleanup must not be nil")
+	}
+	if len(calls) != 1 {
+		t.Fatalf("calls after subscribe = %d, want 1", len(calls))
+	}
+	if calls[0].method != "POST" || calls[0].path != pathMeetingSubscribe {
+		t.Fatalf("subscribe call = %+v", calls[0])
+	}
+	assertSubscriptionRequest(t, calls[0].body, eventTypeMeetingEnded)
+
+	cleanup()
+	if len(calls) != 2 {
+		t.Fatalf("calls after cleanup = %d, want 2", len(calls))
+	}
+	if calls[1].method != "POST" || calls[1].path != pathMeetingUnsubscribe {
+		t.Fatalf("unsubscribe call = %+v", calls[1])
+	}
+	assertSubscriptionRequest(t, calls[1].body, eventTypeMeetingEnded)
+}
+
+func runMeetingEnded(t *testing.T, payload string) VCParticipantMeetingEndedOutput {
+	t.Helper()
+	raw := &event.RawEvent{
+		EventType: eventTypeMeetingEnded,
+		Payload:   json.RawMessage(payload),
+		Timestamp: time.Now(),
+	}
+	got, err := processVCParticipantMeetingEnded(context.Background(), nil, raw, nil)
+	if err != nil {
+		t.Fatalf("Process error: %v", err)
+	}
+	var out VCParticipantMeetingEndedOutput
+	if err := json.Unmarshal(got, &out); err != nil {
+		t.Fatalf("Process output is not valid VCParticipantMeetingEndedOutput JSON: %v\nraw=%s", err, string(got))
+	}
+	return out
+}
--- a/events/vc/preconsume.go
+++ b/events/vc/preconsume.go
@@ -0,0 +1,33 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const cleanupTimeout = 5 * time.Second
+
+func subscriptionPreConsume(eventType, subscribePath, unsubscribePath string) func(context.Context, event.APIClient, map[string]string) (func(), error) {
+	return func(ctx context.Context, rt event.APIClient, _ map[string]string) (func(), error) {
+		if rt == nil {
+			return nil, fmt.Errorf("runtime API client is required for pre-consume subscription")
+		}
+
+		body := map[string]string{"event_type": eventType}
+		if _, err := rt.CallAPI(ctx, "POST", subscribePath, body); err != nil {
+			return nil, err
+		}
+
+		return func() {
+			cleanupCtx, cancel := context.WithTimeout(context.Background(), cleanupTimeout)
+			defer cancel()
+			_, _ = rt.CallAPI(cleanupCtx, "POST", unsubscribePath, body)
+		}, nil
+	}
+}
--- a/events/vc/register.go
+++ b/events/vc/register.go
@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package vc registers VC-domain EventKeys.
+package vc
+
+import (
+	"reflect"
+
+	"github.com/larksuite/cli/internal/event"
+)
+
+const (
+	eventTypeMeetingEnded  = "vc.meeting.participant_meeting_ended_v1"
+	eventTypeNoteGenerated = "vc.note.generated_v1"
+
+	pathMeetingSubscribe   = "/open-apis/vc/v1/meetings/subscription"
+	pathMeetingUnsubscribe = "/open-apis/vc/v1/meetings/unsubscription"
+	pathNoteSubscribe      = "/open-apis/vc/v1/notes/subscription"
+	pathNoteUnsubscribe    = "/open-apis/vc/v1/notes/unsubscription"
+)
+
+// Keys returns all VC-domain EventKey definitions.
+func Keys() []event.KeyDefinition {
+	return []event.KeyDefinition{
+		{
+			Key:         eventTypeMeetingEnded,
+			DisplayName: "Participant meeting ended",
+			Description: "Triggered when a meeting the current user participates in has ended",
+			EventType:   eventTypeMeetingEnded,
+			Schema: event.SchemaDef{
+				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingEndedOutput{})},
+			},
+			Process:    processVCParticipantMeetingEnded,
+			PreConsume: subscriptionPreConsume(eventTypeMeetingEnded, pathMeetingSubscribe, pathMeetingUnsubscribe),
+			Scopes:     []string{"vc:meeting.meetingevent:read"},
+			AuthTypes: []string{
+				"user",
+			},
+			RequiredConsoleEvents: []string{eventTypeMeetingEnded},
+		},
+	}
+}
--- a/events/vc/test_helpers_test.go
+++ b/events/vc/test_helpers_test.go
@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"testing"
+)
+
+type stubAPIClient struct {
+	callFn func(ctx context.Context, method, path string, body any) (json.RawMessage, error)
+}
+
+func (s *stubAPIClient) CallAPI(ctx context.Context, method, path string, body any) (json.RawMessage, error) {
+	if s.callFn == nil {
+		return nil, nil
+	}
+	return s.callFn(ctx, method, path, body)
+}
+
+func assertSubscriptionRequest(t *testing.T, gotBody any, wantEventType string) {
+	t.Helper()
+	want := map[string]string{"event_type": wantEventType}
+	if !reflect.DeepEqual(gotBody, want) {
+		t.Fatalf("request body = %#v, want %#v", gotBody, want)
+	}
+}
--- a/internal/cmdutil/confirm.go
+++ b/internal/cmdutil/confirm.go
@@ -34,7 +34,7 @@ func RequireConfirmation(action string) error {
 			Message: fmt.Sprintf("%s requires confirmation", action),
 			Hint:    "add --yes to confirm",
 			Risk: &output.RiskDetail{
-				Level:  "high-risk-write",
+				Level:  RiskHighRiskWrite,
 				Action: action,
 			},
 		},
--- a/internal/cmdutil/risk.go
+++ b/internal/cmdutil/risk.go
@@ -7,11 +7,20 @@ import "github.com/spf13/cobra"

 const riskLevelAnnotationKey = "risk_level"

+// Risk level constants — the three-tier convention used across the CLI.
+// Use these in place of string literals so the typo radius is one place,
+// not every call site.
+const (
+	RiskRead          = "read"
+	RiskWrite         = "write"
+	RiskHighRiskWrite = "high-risk-write"
+)
+
 // SetRisk stores a command's static risk level on cobra annotations so the
 // help renderer (cmd/root.go) can surface a Risk: line without importing
-// shortcuts/common. Levels follow the three-tier convention: "read" | "write"
-// | "high-risk-write". Framework-level confirmation gating only acts on
-// "high-risk-write".
+// shortcuts/common. Levels follow the three-tier convention: RiskRead |
+// RiskWrite | RiskHighRiskWrite. Framework-level confirmation gating only
+// acts on RiskHighRiskWrite.
 func SetRisk(cmd *cobra.Command, level string) {
 	if level == "" {
 		return
--- a/internal/registry/loader.go
+++ b/internal/registry/loader.go
@@ -22,6 +22,64 @@ var registryFS embed.FS
 // embeddedMetaJSON is set by loader_embedded.go when meta_data.json is compiled in.
 var embeddedMetaJSON []byte

+// EmbeddedMetaJSON returns the raw embedded meta_data.json bytes for callers
+// that need to parse key order or other JSON-level structure not exposed by
+// LoadFromMeta (which loses map insertion order).
+func EmbeddedMetaJSON() []byte {
+	return embeddedMetaJSON
+}
+
+var (
+	embeddedServicesMap  map[string]map[string]interface{} // service name -> spec
+	embeddedServiceNames []string                          // sorted
+	embeddedParseOnce    sync.Once
+)
+
+// parseEmbeddedServices parses embeddedMetaJSON into a service name → spec map
+// without touching mergedServices. Safe to call multiple times (sync.Once).
+func parseEmbeddedServices() {
+	embeddedParseOnce.Do(func() {
+		embeddedServicesMap = make(map[string]map[string]interface{})
+		if len(embeddedMetaJSON) == 0 {
+			return
+		}
+		var wrapper struct {
+			Services []map[string]interface{} `json:"services"`
+		}
+		if err := json.Unmarshal(embeddedMetaJSON, &wrapper); err != nil {
+			return
+		}
+		for _, svc := range wrapper.Services {
+			name, _ := svc["name"].(string)
+			if name == "" {
+				continue
+			}
+			embeddedServicesMap[name] = svc
+		}
+		embeddedServiceNames = make([]string, 0, len(embeddedServicesMap))
+		for name := range embeddedServicesMap {
+			embeddedServiceNames = append(embeddedServiceNames, name)
+		}
+		sort.Strings(embeddedServiceNames)
+	})
+}
+
+// EmbeddedSpec returns the embedded spec for one service, or nil if unknown.
+// Bypasses remote overlay — used for deterministic envelope output.
+func EmbeddedSpec(serviceName string) map[string]interface{} {
+	parseEmbeddedServices()
+	return embeddedServicesMap[serviceName]
+}
+
+// EmbeddedServiceNames returns sorted embedded service names (no overlay).
+// Returns a defensive copy — callers must not mutate the package-level slice.
+func EmbeddedServiceNames() []string {
+	parseEmbeddedServices()
+	out := make([]string, len(embeddedServiceNames))
+	copy(out, embeddedServiceNames)
+	return out
+}
+
 var (
 	mergedServices    = make(map[string]map[string]interface{}) // project name → parsed spec
 	mergedProjectList []string                                  // sorted project names
--- a/internal/schema/assembler.go
+++ b/internal/schema/assembler.go
@@ -0,0 +1,874 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"bytes"
+	"encoding/json"
+	"sort"
+	"strconv"
+	"sync"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/registry"
+)
+
+// MethodKeyOrder records the natural meta_data.json key order for one method's
+// parameters / requestBody / responseBody. Nested object key orders are stored
+// under NestedKeys, keyed by dotted path from the method root
+// (e.g. "responseBody.items.properties").
+type MethodKeyOrder struct {
+	Parameters   []string
+	RequestBody  []string
+	ResponseBody []string
+	NestedKeys   map[string][]string
+}
+
+var (
+	keyOrderIndex    map[string]*MethodKeyOrder // dottedPath -> order
+	keyOrderInitOnce sync.Once
+)
+
+// lookupKeyOrder returns the key-order record for service.resourcePath.method,
+// or nil if the method is not in the embedded data (e.g. remote-cached).
+func lookupKeyOrder(service string, resourcePath []string, method string) *MethodKeyOrder {
+	keyOrderInitOnce.Do(buildKeyOrderIndex)
+	if keyOrderIndex == nil {
+		return nil
+	}
+	dotted := dottedPath(service, resourcePath, method)
+	return keyOrderIndex[dotted]
+}
+
+func dottedPath(service string, resourcePath []string, method string) string {
+	var buf bytes.Buffer
+	buf.WriteString(service)
+	for _, r := range resourcePath {
+		buf.WriteByte('.')
+		buf.WriteString(r)
+	}
+	buf.WriteByte('.')
+	buf.WriteString(method)
+	return buf.String()
+}
+
+// buildKeyOrderIndex parses the embedded meta_data.json bytes once at init,
+// walking services -> resources -> methods -> {parameters,requestBody,responseBody}
+// and recording each map's key insertion order via json.Decoder.Token().
+func buildKeyOrderIndex() {
+	raw := registry.EmbeddedMetaJSON()
+	if len(raw) == 0 {
+		return
+	}
+	keyOrderIndex = make(map[string]*MethodKeyOrder)
+
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	// Top-level: { "services": [...], "version": "..." }
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		if key != "services" {
+			skipValue(dec)
+			continue
+		}
+		if !expectDelim(dec, '[') {
+			return
+		}
+		for dec.More() {
+			parseService(dec)
+		}
+		// closing ]
+		_, _ = dec.Token()
+	}
+}
+
+// parseService consumes one service object inside services[].
+// meta_data.json may emit "resources" before "name", so we first capture both
+// raw fields, then walk resources with the resolved service name.
+func parseService(dec *json.Decoder) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	var serviceName string
+	var resourcesRaw json.RawMessage
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "name":
+			tok, _ := dec.Token()
+			if s, ok := tok.(string); ok {
+				serviceName = s
+			}
+		case "resources":
+			if err := dec.Decode(&resourcesRaw); err != nil {
+				skipValue(dec)
+			}
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token() // closing }
+	if serviceName != "" && len(resourcesRaw) > 0 {
+		subDec := json.NewDecoder(bytes.NewReader(resourcesRaw))
+		parseResources(subDec, serviceName, nil)
+	}
+}
+
+// parseResources walks a resources map (resName -> resource object).
+// resourcePath is the accumulated path of parent resources (for nested resources).
+func parseResources(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		resName, _ := readKey(dec)
+		parseResourceObj(dec, service, append(resourcePath, resName))
+	}
+	_, _ = dec.Token()
+}
+
+// parseResourceObj consumes one resource value: { methods: {...}, ... } and may
+// recurse into nested resources via "resources" key if present.
+func parseResourceObj(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "methods":
+			parseMethods(dec, service, resourcePath)
+		case "resources":
+			parseResources(dec, service, resourcePath)
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+}
+
+// parseMethods consumes the methods map (methodName -> method object).
+func parseMethods(dec *json.Decoder, service string, resourcePath []string) {
+	if !expectDelim(dec, '{') {
+		return
+	}
+	for dec.More() {
+		methodName, _ := readKey(dec)
+		mko := parseMethod(dec)
+		dotted := dottedPath(service, resourcePath, methodName)
+		keyOrderIndex[dotted] = mko
+	}
+	_, _ = dec.Token()
+}
+
+// parseMethod consumes one method object and records key orders.
+func parseMethod(dec *json.Decoder) *MethodKeyOrder {
+	mko := &MethodKeyOrder{NestedKeys: make(map[string][]string)}
+	if !expectDelim(dec, '{') {
+		return mko
+	}
+	for dec.More() {
+		key, _ := readKey(dec)
+		switch key {
+		case "parameters":
+			mko.Parameters = recordObjectKeysRecursive(dec, "parameters", mko.NestedKeys)
+		case "requestBody":
+			mko.RequestBody = recordObjectKeysRecursive(dec, "requestBody", mko.NestedKeys)
+		case "responseBody":
+			mko.ResponseBody = recordObjectKeysRecursive(dec, "responseBody", mko.NestedKeys)
+		default:
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+	return mko
+}
+
+// recordObjectKeysRecursive consumes an object and records the top-level key
+// order. It also recurses into each child's "properties" submap, recording
+// nested orders under prefix.subpath in nestedKeys. Returns the top-level keys
+// in order.
+func recordObjectKeysRecursive(dec *json.Decoder, prefix string, nestedKeys map[string][]string) []string {
+	if !expectDelim(dec, '{') {
+		return nil
+	}
+	var order []string
+	for dec.More() {
+		key, _ := readKey(dec)
+		order = append(order, key)
+		// Each child value is itself an object; we want its nested "properties" order if present.
+		consumeFieldRecursive(dec, prefix+"."+key, nestedKeys)
+	}
+	_, _ = dec.Token()
+	if prefix != "" && len(order) > 0 {
+		nestedKeys[prefix] = order
+	}
+	return order
+}
+
+// consumeFieldRecursive consumes a field object (e.g. one parameter spec) and,
+// if it contains "properties": {...}, recursively records that submap's order.
+func consumeFieldRecursive(dec *json.Decoder, path string, nestedKeys map[string][]string) {
+	tok, err := dec.Token()
+	if err != nil {
+		return
+	}
+	delim, ok := tok.(json.Delim)
+	if !ok || delim != '{' {
+		// Not an object — skip the rest of the value
+		skipValueAfterToken(dec, tok)
+		return
+	}
+	for dec.More() {
+		fieldKey, _ := readKey(dec)
+		if fieldKey == "properties" {
+			recordObjectKeysRecursive(dec, path+".properties", nestedKeys)
+		} else {
+			skipValue(dec)
+		}
+	}
+	_, _ = dec.Token()
+}
+
+// --- json.Decoder helpers ---
+
+func expectDelim(dec *json.Decoder, want json.Delim) bool {
+	tok, err := dec.Token()
+	if err != nil {
+		return false
+	}
+	delim, ok := tok.(json.Delim)
+	return ok && delim == want
+}
+
+func readKey(dec *json.Decoder) (string, error) {
+	tok, err := dec.Token()
+	if err != nil {
+		return "", err
+	}
+	s, _ := tok.(string)
+	return s, nil
+}
+
+// skipValue consumes the next complete value (scalar, object, or array).
+func skipValue(dec *json.Decoder) {
+	tok, err := dec.Token()
+	if err != nil {
+		return
+	}
+	skipValueAfterToken(dec, tok)
+}
+
+func skipValueAfterToken(dec *json.Decoder, tok json.Token) {
+	delim, ok := tok.(json.Delim)
+	if !ok {
+		return
+	}
+	// We started inside a container of type `delim` ({ or [) and must eat
+	// tokens until that container closes, tracking nested containers of any
+	// kind. depth counts how many open containers we are currently inside.
+	_ = delim
+	depth := 1
+	for depth > 0 {
+		t, err := dec.Token()
+		if err != nil {
+			return
+		}
+		if d, ok := t.(json.Delim); ok {
+			switch d {
+			case '{', '[':
+				depth++
+			case '}', ']':
+				depth--
+			}
+		}
+	}
+}
+
+// coerceLiteral converts a meta_data literal (default / enum / example) to
+// the JSON Schema type declared by the field (integer/number/boolean/string).
+// meta_data stores every literal as a string, so without coercion an
+// `integer` field would emit string literals and fail any standard validator.
+// Already-typed values pass through unchanged. Returns (value, true) on
+// success, or (nil, false) when the literal cannot be coerced (caller should
+// drop it).
+func coerceLiteral(fieldType string, raw interface{}) (interface{}, bool) {
+	s, isStr := raw.(string)
+	if !isStr {
+		// Already typed (e.g. meta_data emitted a JSON number/bool directly).
+		return raw, true
+	}
+	switch fieldType {
+	case "integer":
+		if v, err := strconv.ParseInt(s, 10, 64); err == nil {
+			return v, true
+		}
+		return nil, false
+	case "number":
+		if v, err := strconv.ParseFloat(s, 64); err == nil {
+			return v, true
+		}
+		return nil, false
+	case "boolean":
+		switch s {
+		case "true":
+			return true, true
+		case "false":
+			return false, true
+		}
+		return nil, false
+	default: // "string", "" (nested objects), or unknown
+		return s, true
+	}
+}
+
+// sortEnum sorts an enum slice in-place using a comparator appropriate for
+// the declared JSON Schema type, so integer enums end up [1, 2, 10] rather
+// than the lexicographic [1, 10, 2].
+func sortEnum(fieldType string, vals []interface{}) {
+	sort.SliceStable(vals, func(i, j int) bool {
+		switch fieldType {
+		case "integer":
+			ai, _ := vals[i].(int64)
+			bi, _ := vals[j].(int64)
+			return ai < bi
+		case "number":
+			af, _ := vals[i].(float64)
+			bf, _ := vals[j].(float64)
+			return af < bf
+		case "boolean":
+			ab, _ := vals[i].(bool)
+			bb, _ := vals[j].(bool)
+			return !ab && bb // false < true
+		default:
+			as, _ := vals[i].(string)
+			bs, _ := vals[j].(string)
+			return as < bs
+		}
+	})
+}
+
+// convertProperty recursively converts one meta_data field map into a Property.
+// nestedPath is the dotted lookup key into the current method's NestedKeys map
+// (e.g. "responseBody.items.properties"). Empty path = top-level, no nested
+// lookup needed.
+func convertProperty(field map[string]interface{}, nestedPath string) Property {
+	var p Property
+
+	rawType, _ := field["type"].(string)
+	switch rawType {
+	case "file":
+		p.Type = "string"
+		p.Format = "binary"
+	case "list":
+		// meta_data uses non-standard "list" on a couple of fields;
+		// translate to JSON Schema "array" so validators accept it.
+		p.Type = "array"
+	default:
+		p.Type = rawType
+	}
+
+	if s, ok := field["description"].(string); ok {
+		p.Description = s
+	}
+	if v, ok := field["default"]; ok {
+		// Coerce default literal to match the declared JSON Schema type so
+		// validators do not reject e.g. {type:"integer", default:"500"}.
+		// When coercion fails (e.g. default:"" on an integer field, which
+		// meta_data uses to mean "no default"), omit the field entirely
+		// instead of emitting a type-mismatched default — the result is a
+		// missing `default` key rather than a contract violation.
+		if coerced, ok := coerceLiteral(p.Type, v); ok {
+			p.Default = coerced
+		}
+	}
+	if v, ok := field["example"]; ok {
+		// meta_data stores examples as strings even when the field is integer/
+		// boolean/number; coerce to the declared type so downstream validators
+		// accept the envelope. Drop on coerce failure (same policy as default).
+		if coerced, ok := coerceLiteral(p.Type, v); ok {
+			p.Example = coerced
+		}
+	}
+
+	// min / max are stored as strings in meta_data; parse on best-effort.
+	if minStr, ok := field["min"].(string); ok && minStr != "" {
+		if v, err := strconv.ParseFloat(minStr, 64); err == nil {
+			p.Minimum = &v
+		}
+	}
+	if maxStr, ok := field["max"].(string); ok && maxStr != "" {
+		if v, err := strconv.ParseFloat(maxStr, 64); err == nil {
+			p.Maximum = &v
+		}
+	}
+
+	// enum: prefer existing "enum" array; else extract from options[].value.
+	// Values are typed per p.Type so integer fields get integer enums, etc.
+	// (JSON Schema 2020-12 requires enum value types to match the declared
+	// type — meta_data stores everything as strings.)
+	if enumRaw, ok := field["enum"].([]interface{}); ok && len(enumRaw) > 0 {
+		for _, e := range enumRaw {
+			if v, ok := coerceLiteral(p.Type, e); ok {
+				p.Enum = append(p.Enum, v)
+			}
+		}
+		// Numeric/boolean enums get sorted (no inherent meaning in meta_data
+		// order); string enums keep meta_data order, which sometimes carries
+		// semantic priority (e.g. image_type ["message","avatar"]).
+		if p.Type != "string" && p.Type != "" {
+			sortEnum(p.Type, p.Enum)
+		}
+	} else if optsRaw, ok := field["options"].([]interface{}); ok && len(optsRaw) > 0 {
+		seen := make(map[string]bool)
+		for _, o := range optsRaw {
+			om, ok := o.(map[string]interface{})
+			if !ok {
+				continue
+			}
+			raw, ok := om["value"].(string)
+			if !ok || seen[raw] {
+				continue
+			}
+			seen[raw] = true
+			if v, ok := coerceLiteral(p.Type, raw); ok {
+				p.Enum = append(p.Enum, v)
+			}
+		}
+		// Same policy as the `enum` branch: numeric/boolean enums get sorted
+		// (no semantic meaning in source order); string enums keep meta_data
+		// order, which may carry semantic priority.
+		if p.Type != "string" && p.Type != "" {
+			sortEnum(p.Type, p.Enum)
+		}
+	}
+
+	// nested properties: recurse
+	if propsRaw, ok := field["properties"].(map[string]interface{}); ok && len(propsRaw) > 0 {
+		nested, nestedRequired := buildOrderedProps(propsRaw, nestedPath)
+		if p.Type == "array" {
+			// meta_data quirk: array element schema is wrapped in "properties".
+			// Unfold into Items: { type: "object", properties: <nested> }
+			p.Items = &Property{
+				Type:       "object",
+				Properties: nested,
+				Required:   nestedRequired,
+			}
+			// Property.Properties stays nil for arrays
+		} else {
+			if p.Type == "" {
+				p.Type = "object" // infer
+			}
+			p.Properties = nested
+			p.Required = nestedRequired
+		}
+	}
+
+	// array items fallback: emit `items: {}` (any schema) for every array that
+	// meta_data does not describe an element shape for — whether it arrived as
+	// "list" or natively as "array". Without this, typeless arrays (e.g. arrays
+	// of bare ID strings) violate the L1 lint rule and are not JSON Schema valid
+	// for consumers that require `items`.
+	if p.Type == "array" && p.Items == nil {
+		p.Items = &Property{}
+	}
+
+	return p
+}
+
+// buildOrderedProps converts a map[string]interface{} of field specs into an
+// OrderedProps plus the alphabetized list of child keys marked `required:true`
+// in meta_data. Callers attach that list to the enclosing object's `required`,
+// so nested objects faithfully report their call contract (top-level required
+// is handled separately by buildInputSchema).
+func buildOrderedProps(raw map[string]interface{}, nestedPath string) (*OrderedProps, []string) {
+	op := &OrderedProps{Map: make(map[string]Property, len(raw))}
+
+	var required []string
+	keys := orderedKeys(raw, nestedPath)
+	for _, k := range keys {
+		fieldRaw, _ := raw[k].(map[string]interface{})
+		op.Order = append(op.Order, k)
+		op.Map[k] = convertProperty(fieldRaw, nestedPath+"."+k+".properties")
+		if req, _ := fieldRaw["required"].(bool); req {
+			required = append(required, k)
+		}
+	}
+	sort.Strings(required)
+	return op, required
+}
+
+// currentMethodOrder is the per-method key-order context used by orderedKeys.
+// It is set inside AssembleEnvelope (under assembleMu) and reset on return.
+var currentMethodOrder *MethodKeyOrder
+
+// parseAffordance lifts the affordance overlay from a method's raw meta_data.json
+// entry into a typed *Affordance. Returns nil when the field is absent, malformed,
+// or carries no populated subfields.
+//
+// Affordance is authored in larksuite-cli-registry's registry-config.yaml under
+// overrides.<resource>.<method>.affordance and flows through gen-registry.py's
+// deep_merge into the embedded meta_data.json.
+func parseAffordance(raw interface{}) *Affordance {
+	if raw == nil {
+		return nil
+	}
+	b, err := json.Marshal(raw)
+	if err != nil {
+		return nil
+	}
+	var a Affordance
+	if err := json.Unmarshal(b, &a); err != nil {
+		return nil
+	}
+	if len(a.UseWhen) == 0 && len(a.DoNotUseWhen) == 0 && len(a.Prerequisites) == 0 && len(a.Examples) == 0 && len(a.Related) == 0 {
+		return nil
+	}
+	return &a
+}
+
+// convertAccessTokens translates from_meta accessTokens (uses "tenant") into
+// CLI --as form (uses "bot"). The result is deduped and sorted alphabetically.
+// Unknown tokens are dropped. Returns an empty slice for nil/empty input.
+func convertAccessTokens(raw []interface{}) []string {
+	seen := make(map[string]bool)
+	for _, t := range raw {
+		s, ok := t.(string)
+		if !ok {
+			continue
+		}
+		switch s {
+		case "tenant":
+			seen["bot"] = true
+		case "user":
+			seen["user"] = true
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for k := range seen {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// buildMeta produces the _meta extension namespace.
+func buildMeta(method map[string]interface{}) *Meta {
+	m := &Meta{
+		EnvelopeVersion: "1.0",
+		RequiredScopes:  []string{}, // never nil for stable JSON
+	}
+
+	if scopesRaw, ok := method["scopes"].([]interface{}); ok {
+		for _, s := range scopesRaw {
+			if str, ok := s.(string); ok {
+				m.Scopes = append(m.Scopes, str)
+			}
+		}
+	}
+	if rsRaw, ok := method["requiredScopes"].([]interface{}); ok {
+		for _, s := range rsRaw {
+			if str, ok := s.(string); ok {
+				m.RequiredScopes = append(m.RequiredScopes, str)
+			}
+		}
+	}
+
+	atRaw, _ := method["accessTokens"].([]interface{})
+	m.AccessTokens = convertAccessTokens(atRaw)
+
+	m.Danger, _ = method["danger"].(bool)
+
+	if risk, _ := method["risk"].(string); risk != "" {
+		m.Risk = risk
+	} else {
+		m.Risk = cmdutil.RiskRead
+	}
+
+	if docURL, _ := method["docUrl"].(string); docURL != "" {
+		m.DocURL = docURL
+	}
+
+	m.Affordance = parseAffordance(method["affordance"])
+	return m
+}
+
+// buildInputSchema produces the inputSchema for one API method.
+//
+// Top-level shape:
+//
+//	{ type: object,
+//	  required: [<"params" if any param required>, <"data" if any body required>],
+//	  properties: {
+//	    params: { type: object, required: [...], properties: { ...path/query fields } },  // only if method has parameters
+//	    data:   { type: object, required: [...], properties: { ...body fields } },         // only if method has requestBody
+//	    yes:    { type: boolean, default: false, ... }                                     // only when risk == "high-risk-write"
+//	  } }
+//
+// The params / data wrapping mirrors the CLI's actual flag layout:
+// path+query → --params JSON, body → --data JSON, file → --file. AI consumers
+// can pluck inputSchema.properties.params and pass it verbatim to --params.
+//
+// Caller must set currentMethodOrder for property-order preservation.
+func buildInputSchema(method map[string]interface{}) *InputSchema {
+	is := &InputSchema{
+		Type:       "object",
+		Required:   []string{}, // never nil — stable envelope shape
+		Properties: &OrderedProps{Map: make(map[string]Property)},
+	}
+
+	// Build the "params" sub-object from method.parameters (path + query).
+	paramsRaw, _ := method["parameters"].(map[string]interface{})
+	paramsProps := &OrderedProps{Map: make(map[string]Property)}
+	var paramsRequired []string
+	for _, k := range orderedKeys(paramsRaw, "parameters") {
+		field, _ := paramsRaw[k].(map[string]interface{})
+		prop := convertProperty(field, "parameters."+k+".properties")
+		paramsProps.Order = append(paramsProps.Order, k)
+		paramsProps.Map[k] = prop
+		if req, _ := field["required"].(bool); req {
+			paramsRequired = append(paramsRequired, k)
+		}
+	}
+	if len(paramsProps.Order) > 0 {
+		sort.Strings(paramsRequired)
+		is.Properties.Order = append(is.Properties.Order, "params")
+		is.Properties.Map["params"] = Property{
+			Type:       "object",
+			Required:   paramsRequired,
+			Properties: paramsProps,
+		}
+		if len(paramsRequired) > 0 {
+			is.Required = append(is.Required, "params")
+		}
+	}
+
+	// Split method.requestBody into two buckets:
+	//   - data: non-file body fields → corresponds to CLI --data JSON
+	//   - file: type:file body fields → corresponds to CLI --file <key>=<path>
+	// File fields are kept *out* of `data` so the schema mirrors the actual
+	// CLI flag dispatch: --file owns one wire format (multipart upload),
+	// --data owns the rest (JSON body).
+	bodyRaw, _ := method["requestBody"].(map[string]interface{})
+	dataProps := &OrderedProps{Map: make(map[string]Property)}
+	fileProps := &OrderedProps{Map: make(map[string]Property)}
+	var dataRequired []string
+	var fileRequired []string
+	for _, k := range orderedKeys(bodyRaw, "requestBody") {
+		field, _ := bodyRaw[k].(map[string]interface{})
+		prop := convertProperty(field, "requestBody."+k+".properties")
+		isFile := false
+		if t, _ := field["type"].(string); t == "file" {
+			isFile = true
+		}
+		if isFile {
+			fileProps.Order = append(fileProps.Order, k)
+			fileProps.Map[k] = prop
+			if req, _ := field["required"].(bool); req {
+				fileRequired = append(fileRequired, k)
+			}
+		} else {
+			dataProps.Order = append(dataProps.Order, k)
+			dataProps.Map[k] = prop
+			if req, _ := field["required"].(bool); req {
+				dataRequired = append(dataRequired, k)
+			}
+		}
+	}
+	if len(dataProps.Order) > 0 {
+		sort.Strings(dataRequired)
+		is.Properties.Order = append(is.Properties.Order, "data")
+		is.Properties.Map["data"] = Property{
+			Type:       "object",
+			Required:   dataRequired,
+			Properties: dataProps,
+		}
+		if len(dataRequired) > 0 {
+			is.Required = append(is.Required, "data")
+		}
+	}
+	if len(fileProps.Order) > 0 {
+		sort.Strings(fileRequired)
+		is.Properties.Order = append(is.Properties.Order, "file")
+		is.Properties.Map["file"] = Property{
+			Type:        "object",
+			Description: "Binary file uploads. Each property is a file field with format:binary; CLI maps each to --file <key>=<path>.",
+			Required:    fileRequired,
+			Properties:  fileProps,
+		}
+		if len(fileRequired) > 0 {
+			is.Required = append(is.Required, "file")
+		}
+	}
+
+	// high-risk-write injects a top-level `yes` confirmation flag — sibling
+	// of params/data. It is a CLI gate (consumed by lark-cli, not sent to
+	// the backend), not an API field.
+	if risk, _ := method["risk"].(string); risk == cmdutil.RiskHighRiskWrite {
+		is.Properties.Order = append(is.Properties.Order, "yes")
+		falseVal := false
+		is.Properties.Map["yes"] = Property{
+			Type:        "boolean",
+			Default:     falseVal,
+			Description: "CLI confirmation gate. Must be true to execute; lark-cli rejects with confirmation_required if absent or false. Not sent to the backend.",
+		}
+		// yes is intentionally NOT added to top-level Required; the gate is
+		// enforced semantically (yes==true) by the CLI, not structurally.
+	}
+
+	sort.Strings(is.Required) // alphabetical
+	return is
+}
+
+// buildOutputSchema produces the outputSchema for one API method.
+func buildOutputSchema(method map[string]interface{}) *OutputSchema {
+	os := &OutputSchema{
+		Type:       "object",
+		Properties: &OrderedProps{Map: make(map[string]Property)},
+	}
+	respRaw, _ := method["responseBody"].(map[string]interface{})
+	for _, k := range orderedKeys(respRaw, "responseBody") {
+		field, _ := respRaw[k].(map[string]interface{})
+		os.Properties.Order = append(os.Properties.Order, k)
+		os.Properties.Map[k] = convertProperty(field, "responseBody."+k+".properties")
+	}
+	return os
+}
+
+// assembleMu serializes AssembleEnvelope calls so that the package-level
+// currentMethodOrder pointer is safe for concurrent callers.
+var assembleMu sync.Mutex
+
+// AssembleEnvelope is the main entry point: takes a service / resource path /
+// method name plus its meta_data spec, and produces a fully assembled MCP
+// envelope. Output is fully determined by inputs (same arguments → same
+// envelope), but assembly briefly publishes the per-method key-order context
+// through the package-level currentMethodOrder so orderedKeys can reach it
+// without threading it through every helper. assembleMu serializes that
+// publish, which is why concurrent callers are still safe — they queue
+// rather than run in parallel.
+//
+// If parallelism becomes a bottleneck, replace currentMethodOrder with an
+// assembler struct or pass *MethodKeyOrder explicitly down the call chain.
+func AssembleEnvelope(serviceName string, resourcePath []string, methodName string, method map[string]interface{}) Envelope {
+	assembleMu.Lock()
+	defer assembleMu.Unlock()
+	currentMethodOrder = lookupKeyOrder(serviceName, resourcePath, methodName)
+	defer func() { currentMethodOrder = nil }()
+
+	name := serviceName
+	for _, r := range resourcePath {
+		name += " " + r
+	}
+	name += " " + methodName
+
+	desc, _ := method["description"].(string)
+
+	return Envelope{
+		Name:         name,
+		Description:  desc,
+		InputSchema:  buildInputSchema(method),
+		OutputSchema: buildOutputSchema(method),
+		Meta:         buildMeta(method),
+	}
+}
+
+// MethodFilter is an optional predicate used by AssembleService and
+// AssembleAll to filter methods (e.g. by access token for strict mode).
+// Pass nil to include all methods.
+type MethodFilter func(method map[string]interface{}) bool
+
+// AssembleService assembles all methods under one service into a sorted
+// envelope slice (sorted by Envelope.Name ascending).
+func AssembleService(serviceName string, spec map[string]interface{}, filter MethodFilter) []Envelope {
+	if spec == nil {
+		return nil
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	var out []Envelope
+	walkMethods(resources, nil, func(resourcePath []string, methodName string, method map[string]interface{}) {
+		if filter != nil && !filter(method) {
+			return
+		}
+		out = append(out, AssembleEnvelope(serviceName, resourcePath, methodName, method))
+	})
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// AssembleAll assembles every embedded service into one big sorted slice.
+// Uses embedded data only (bypasses remote overlay) so envelope output is
+// deterministic across machines (CI vs dev vs different user brands).
+func AssembleAll(filter MethodFilter) []Envelope {
+	var out []Envelope
+	for _, svc := range registry.EmbeddedServiceNames() {
+		spec := registry.EmbeddedSpec(svc)
+		out = append(out, AssembleService(svc, spec, filter)...)
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+// walkMethods recursively walks resources -> methods, calling visit for each
+// terminal method. It supports nested resources via the optional "resources"
+// key inside a resource value (matches meta_data.json structure).
+func walkMethods(resources map[string]interface{}, parentPath []string,
+	visit func(resourcePath []string, methodName string, method map[string]interface{})) {
+	for resName, resRaw := range resources {
+		resMap, ok := resRaw.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		curPath := append(append([]string(nil), parentPath...), resName)
+		if methods, ok := resMap["methods"].(map[string]interface{}); ok {
+			for mName, mRaw := range methods {
+				if m, ok := mRaw.(map[string]interface{}); ok {
+					visit(curPath, mName, m)
+				}
+			}
+		}
+		if nested, ok := resMap["resources"].(map[string]interface{}); ok {
+			walkMethods(nested, curPath, visit)
+		}
+	}
+}
+
+// orderedKeys returns the keys of raw in their meta_data natural order if
+// the current per-method key-order context has them recorded; otherwise
+// alphabetical fallback.
+func orderedKeys(raw map[string]interface{}, nestedPath string) []string {
+	if currentMethodOrder != nil && nestedPath != "" {
+		if order, ok := currentMethodOrder.NestedKeys[nestedPath]; ok {
+			// Filter to keys that actually exist in raw (defensive)
+			out := make([]string, 0, len(order))
+			seen := make(map[string]bool)
+			for _, k := range order {
+				if _, ok := raw[k]; ok {
+					out = append(out, k)
+					seen[k] = true
+				}
+			}
+			// Append any keys present in raw but missing from order (defensive),
+			// alphabetically for determinism.
+			var extra []string
+			for k := range raw {
+				if !seen[k] {
+					extra = append(extra, k)
+				}
+			}
+			sort.Strings(extra)
+			out = append(out, extra...)
+			return out
+		}
+	}
+	// Fallback: alphabetical
+	keys := make([]string, 0, len(raw))
+	for k := range raw {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
--- a/internal/schema/assembler_test.go
+++ b/internal/schema/assembler_test.go
@@ -0,0 +1,781 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"encoding/json"
+	"os"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/registry"
+)
+
+// TestMain isolates registry-backed tests from any host ~/.lark-cli cache so
+// the suite gives the same answer on every machine. Without this, a stale
+// local remote_meta.json could surface methods that aren't in the embedded
+// snapshot (or alter their data) depending on the contributor's environment.
+//
+// Note: os.Exit skips deferred functions, so cleanup is done explicitly
+// after m.Run before exiting.
+func TestMain(m *testing.M) {
+	dir, err := os.MkdirTemp("", "schema-test-cfg-*")
+	if err != nil {
+		// Surface the failure rather than silently running against the host
+		// cache — that defeats the whole purpose of this isolation.
+		println("schema test setup: MkdirTemp failed:", err.Error())
+		os.Exit(2)
+	}
+	os.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	os.Setenv("LARKSUITE_CLI_REMOTE_META", "off") // never touch network
+	code := m.Run()
+	os.RemoveAll(dir)
+	os.Exit(code)
+}
+
+func TestKeyOrderIndex_ImReactionsList(t *testing.T) {
+	// We only assert key-set membership, not absolute order — the upstream
+	// meta_data API does not guarantee a stable JSON key sequence across
+	// fetches, so hard-coding the order makes CI flaky. Order preservation
+	// from input to output is tested separately in TestBuildInputSchema_*.
+	order := lookupKeyOrder("im", []string{"reactions"}, "list")
+	if order == nil {
+		t.Fatal("expected key order for im.reactions.list, got nil")
+	}
+	wantParams := map[string]bool{
+		"message_id": true, "reaction_type": true, "page_token": true,
+		"page_size": true, "user_id_type": true,
+	}
+	if got, want := len(order.Parameters), len(wantParams); got != want {
+		t.Errorf("parameters count = %d, want %d (got %v)", got, want, order.Parameters)
+	}
+	for _, k := range order.Parameters {
+		if !wantParams[k] {
+			t.Errorf("unexpected parameter key %q", k)
+		}
+	}
+	// im.reactions.list 是 GET，没有 requestBody
+	if len(order.RequestBody) != 0 {
+		t.Errorf("expected empty RequestBody, got %v", order.RequestBody)
+	}
+}
+
+func TestKeyOrderIndex_ImImagesCreate(t *testing.T) {
+	// Membership-only assertion; see comment on TestKeyOrderIndex_ImReactionsList.
+	order := lookupKeyOrder("im", []string{"images"}, "create")
+	if order == nil {
+		t.Fatal("expected key order for im.images.create, got nil")
+	}
+	wantBody := map[string]bool{"image_type": true, "image": true}
+	if got, want := len(order.RequestBody), len(wantBody); got != want {
+		t.Errorf("requestBody count = %d, want %d (got %v)", got, want, order.RequestBody)
+	}
+	for _, k := range order.RequestBody {
+		if !wantBody[k] {
+			t.Errorf("unexpected requestBody key %q", k)
+		}
+	}
+}
+
+func TestKeyOrderIndex_UnknownPath(t *testing.T) {
+	// 远端缓存的命令（不在 embedded 内）查不到 key order，返回 nil 走字母序兜底
+	order := lookupKeyOrder("nonexistent_service", []string{"foo"}, "bar")
+	if order != nil {
+		t.Errorf("expected nil for unknown path, got %+v", order)
+	}
+}
+
+func TestConvertProperty_BasicTypes(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    map[string]interface{}
+		wantType string
+	}{
+		{"string", map[string]interface{}{"type": "string"}, "string"},
+		{"integer", map[string]interface{}{"type": "integer"}, "integer"},
+		{"boolean", map[string]interface{}{"type": "boolean"}, "boolean"},
+		{"number", map[string]interface{}{"type": "number"}, "number"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := convertProperty(tt.input, "")
+			if got.Type != tt.wantType {
+				t.Errorf("Type = %q, want %q", got.Type, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestConvertProperty_FileBinary(t *testing.T) {
+	input := map[string]interface{}{"type": "file", "description": "upload"}
+	got := convertProperty(input, "")
+	if got.Type != "string" {
+		t.Errorf("Type = %q, want \"string\"", got.Type)
+	}
+	if got.Format != "binary" {
+		t.Errorf("Format = %q, want \"binary\"", got.Format)
+	}
+}
+
+func TestConvertProperty_OptionsToEnum(t *testing.T) {
+	input := map[string]interface{}{
+		"type": "string",
+		"options": []interface{}{
+			map[string]interface{}{"value": "banana"},
+			map[string]interface{}{"value": "apple"},
+			map[string]interface{}{"value": "banana"}, // duplicate
+		},
+	}
+	got := convertProperty(input, "")
+	// string enums preserve source order (deduped), matching the `enum`
+	// branch. Numeric/boolean enums would still be sorted by value.
+	want := []interface{}{"banana", "apple"}
+	if !reflect.DeepEqual(got.Enum, want) {
+		t.Errorf("Enum = %v, want %v", got.Enum, want)
+	}
+}
+
+func TestConvertProperty_EnumPassThrough(t *testing.T) {
+	input := map[string]interface{}{
+		"type": "string",
+		"enum": []interface{}{"x", "y"},
+	}
+	got := convertProperty(input, "")
+	want := []interface{}{"x", "y"} // pass through, no sort
+	if !reflect.DeepEqual(got.Enum, want) {
+		t.Errorf("Enum = %v, want %v", got.Enum, want)
+	}
+}
+
+func TestConvertProperty_EnumIntegerCoerce(t *testing.T) {
+	input := map[string]interface{}{
+		"type": "integer",
+		"options": []interface{}{
+			map[string]interface{}{"value": "10"},
+			map[string]interface{}{"value": "1"},
+			map[string]interface{}{"value": "2"},
+		},
+	}
+	got := convertProperty(input, "")
+	want := []interface{}{int64(1), int64(2), int64(10)} // typed + numerically sorted
+	if !reflect.DeepEqual(got.Enum, want) {
+		t.Errorf("Enum = %v, want %v", got.Enum, want)
+	}
+}
+
+func TestConvertProperty_ListTypeFallback(t *testing.T) {
+	input := map[string]interface{}{
+		"type":        "list",
+		"description": "ids",
+	}
+	got := convertProperty(input, "")
+	if got.Type != "array" {
+		t.Errorf("Type = %q, want %q", got.Type, "array")
+	}
+	if got.Items == nil {
+		t.Fatalf("Items = nil, want non-nil (any-schema fallback)")
+	}
+}
+
+func TestConvertProperty_MinMaxParsing(t *testing.T) {
+	input := map[string]interface{}{"type": "integer", "min": "10", "max": "50"}
+	got := convertProperty(input, "")
+	if got.Minimum == nil || *got.Minimum != 10.0 {
+		t.Errorf("Minimum = %v, want 10", got.Minimum)
+	}
+	if got.Maximum == nil || *got.Maximum != 50.0 {
+		t.Errorf("Maximum = %v, want 50", got.Maximum)
+	}
+}
+
+func TestConvertProperty_MinMaxInvalid(t *testing.T) {
+	input := map[string]interface{}{"type": "integer", "min": "not_a_number"}
+	got := convertProperty(input, "")
+	if got.Minimum != nil {
+		t.Errorf("Minimum = %v, want nil for unparseable min", got.Minimum)
+	}
+}
+
+func TestConvertProperty_ArrayWithProperties(t *testing.T) {
+	// meta_data quirk: array element schema is in "properties" not "items"
+	input := map[string]interface{}{
+		"type": "array",
+		"properties": map[string]interface{}{
+			"id":   map[string]interface{}{"type": "string"},
+			"name": map[string]interface{}{"type": "string"},
+		},
+	}
+	got := convertProperty(input, "")
+	if got.Type != "array" {
+		t.Fatalf("Type = %q, want \"array\"", got.Type)
+	}
+	if got.Items == nil {
+		t.Fatal("Items is nil, want non-nil")
+	}
+	if got.Items.Type != "object" {
+		t.Errorf("Items.Type = %q, want \"object\"", got.Items.Type)
+	}
+	if got.Items.Properties == nil || len(got.Items.Properties.Map) != 2 {
+		t.Errorf("Items.Properties did not contain both id and name")
+	}
+	if got.Properties != nil {
+		t.Error("array Property must not have top-level Properties after unfold")
+	}
+}
+
+func TestConvertProperty_ObjectWithProperties(t *testing.T) {
+	input := map[string]interface{}{
+		"type": "object",
+		"properties": map[string]interface{}{
+			"x": map[string]interface{}{"type": "string"},
+		},
+	}
+	got := convertProperty(input, "")
+	if got.Type != "object" {
+		t.Errorf("Type = %q, want \"object\"", got.Type)
+	}
+	if got.Properties == nil || got.Properties.Map["x"].Type != "string" {
+		t.Errorf("nested Properties not preserved")
+	}
+}
+
+func TestConvertProperty_InferObjectFromProperties(t *testing.T) {
+	input := map[string]interface{}{
+		"properties": map[string]interface{}{
+			"y": map[string]interface{}{"type": "string"},
+		},
+	}
+	got := convertProperty(input, "")
+	if got.Type != "object" {
+		t.Errorf("Type = %q, want \"object\" (inferred)", got.Type)
+	}
+}
+
+func TestConvertProperty_DropsRefAndAnnotations(t *testing.T) {
+	input := map[string]interface{}{
+		"type":        "string",
+		"ref":         "operator",
+		"annotations": []interface{}{"readOnly"},
+		"enumName":    "FooEnum",
+	}
+	got := convertProperty(input, "")
+	// 这些字段直接被丢弃；Property 结构里也没存这些字段，断言只有 type 设置即可
+	if got.Type != "string" {
+		t.Errorf("Type = %q", got.Type)
+	}
+}
+
+func TestConvertProperty_DescriptionDefaultExample(t *testing.T) {
+	input := map[string]interface{}{
+		"type":        "string",
+		"description": "hello\nworld",
+		"default":     "",
+		"example":     "ex",
+	}
+	got := convertProperty(input, "")
+	if got.Description != "hello\nworld" {
+		t.Errorf("Description not preserved verbatim")
+	}
+	if got.Default != "" {
+		t.Errorf("Default = %v, want empty string (preserved)", got.Default)
+	}
+	if got.Example != "ex" {
+		t.Errorf("Example = %v, want \"ex\"", got.Example)
+	}
+}
+
+func TestBuildInputSchema_ReactionsList(t *testing.T) {
+	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
+
+	is := buildInputSchema(method)
+
+	if is.Type != "object" {
+		t.Errorf("Type = %q, want \"object\"", is.Type)
+	}
+	// top-level required: ["params"] because message_id is a required path param
+	if !reflect.DeepEqual(is.Required, []string{"params"}) {
+		t.Errorf("Required = %v, want [params]", is.Required)
+	}
+	// top-level properties only contains "params" (no body fields, no high-risk-write)
+	if !reflect.DeepEqual(is.Properties.Order, []string{"params"}) {
+		t.Errorf("top-level properties order = %v, want [params]", is.Properties.Order)
+	}
+	// params sub-object: required + property order
+	params := is.Properties.Map["params"]
+	if params.Type != "object" {
+		t.Errorf("params.Type = %q, want \"object\"", params.Type)
+	}
+	if !reflect.DeepEqual(params.Required, []string{"message_id"}) {
+		t.Errorf("params.Required = %v, want [message_id]", params.Required)
+	}
+	if !reflect.DeepEqual(params.Properties.Order, mko.Parameters) {
+		t.Errorf("params.properties order = %v, want (from key index) %v",
+			params.Properties.Order, mko.Parameters)
+	}
+}
+
+func TestBuildInputSchema_ImagesCreate_FileAndBody(t *testing.T) {
+	method := loadMethodFromRegistry(t, "im", []string{"images"}, "create")
+	currentMethodOrder = lookupKeyOrder("im", []string{"images"}, "create")
+	defer func() { currentMethodOrder = nil }()
+
+	is := buildInputSchema(method)
+
+	// top-level required: ["data", "file"] — image_type body required + image file required
+	if !reflect.DeepEqual(is.Required, []string{"data", "file"}) {
+		t.Errorf("Required = %v, want [data, file]", is.Required)
+	}
+	// top-level properties: data (for non-file body) + file (for binary upload)
+	if !reflect.DeepEqual(is.Properties.Order, []string{"data", "file"}) {
+		t.Errorf("top-level properties order = %v, want [data, file]", is.Properties.Order)
+	}
+	// data sub-object carries only non-file body fields (image_type)
+	data := is.Properties.Map["data"]
+	if !reflect.DeepEqual(data.Required, []string{"image_type"}) {
+		t.Errorf("data.Required = %v, want [image_type]", data.Required)
+	}
+	if !reflect.DeepEqual(data.Properties.Order, []string{"image_type"}) {
+		t.Errorf("data.properties order = %v, want [image_type]", data.Properties.Order)
+	}
+	if it := data.Properties.Map["image_type"]; !reflect.DeepEqual(it.Enum, []interface{}{"message", "avatar"}) {
+		t.Errorf("image_type unexpected: %+v", it)
+	}
+	if _, isFile := data.Properties.Map["image"]; isFile {
+		t.Errorf("image (file field) should NOT appear in data sub-object")
+	}
+
+	// file sub-object carries the binary upload field
+	file := is.Properties.Map["file"]
+	if file.Type != "object" {
+		t.Errorf("file.Type = %q, want \"object\"", file.Type)
+	}
+	if !reflect.DeepEqual(file.Required, []string{"image"}) {
+		t.Errorf("file.Required = %v, want [image]", file.Required)
+	}
+	if !reflect.DeepEqual(file.Properties.Order, []string{"image"}) {
+		t.Errorf("file.properties order = %v, want [image]", file.Properties.Order)
+	}
+	img := file.Properties.Map["image"]
+	if img.Type != "string" {
+		t.Errorf("image.Type = %q, want \"string\"", img.Type)
+	}
+	if img.Format != "binary" {
+		t.Errorf("image.Format = %q, want \"binary\"", img.Format)
+	}
+}
+
+func TestBuildInputSchema_HighRiskWriteInjectsYes(t *testing.T) {
+	// Synthesized method to avoid registry-overlay variance (remote cache may
+	// strip `risk` field); buildInputSchema only cares about the method map.
+	method := map[string]interface{}{
+		"risk": "high-risk-write",
+		"parameters": map[string]interface{}{
+			"message_id": map[string]interface{}{
+				"type":     "string",
+				"location": "path",
+				"required": true,
+			},
+		},
+	}
+	currentMethodOrder = nil
+	defer func() { currentMethodOrder = nil }()
+
+	is := buildInputSchema(method)
+
+	// yes lives at inputSchema.properties.yes (sibling of params/data)
+	yes, ok := is.Properties.Map["yes"]
+	if !ok {
+		t.Fatal("expected top-level `yes` property in high-risk-write envelope, not found")
+	}
+	if yes.Type != "boolean" {
+		t.Errorf("yes.Type = %q, want \"boolean\"", yes.Type)
+	}
+	if v, _ := yes.Default.(bool); v != false {
+		t.Errorf("yes.Default = %v, want false", yes.Default)
+	}
+	// yes must NOT be in top-level required
+	for _, r := range is.Required {
+		if r == "yes" {
+			t.Errorf("`yes` should not appear in top-level required")
+		}
+	}
+	// yes is appended to properties.Order
+	last := is.Properties.Order[len(is.Properties.Order)-1]
+	if last != "yes" {
+		t.Errorf("`yes` should be last in properties.Order, got: %v", is.Properties.Order)
+	}
+}
+
+func TestBuildInputSchema_NoYesForReadRisk(t *testing.T) {
+	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
+
+	is := buildInputSchema(method)
+	if _, ok := is.Properties.Map["yes"]; ok {
+		t.Errorf("`yes` must not be injected for risk=read")
+	}
+}
+
+func TestBuildOutputSchema_ReactionsList(t *testing.T) {
+	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	mko := lookupKeyOrder("im", []string{"reactions"}, "list")
+	currentMethodOrder = mko
+	defer func() { currentMethodOrder = nil }()
+
+	os := buildOutputSchema(method)
+
+	if os.Type != "object" {
+		t.Errorf("Type = %q, want \"object\"", os.Type)
+	}
+	// Top-level response: has_more, page_token, items
+	if _, ok := os.Properties.Map["items"]; !ok {
+		t.Fatal("items not found in outputSchema")
+	}
+	items := os.Properties.Map["items"]
+	if items.Type != "array" {
+		t.Errorf("items.Type = %q, want \"array\"", items.Type)
+	}
+	if items.Items == nil {
+		t.Fatal("items.Items is nil (array unfold failed)")
+	}
+	if items.Items.Type != "object" {
+		t.Errorf("items.Items.Type = %q, want \"object\"", items.Items.Type)
+	}
+}
+
+func TestConvertAccessTokens(t *testing.T) {
+	tests := []struct {
+		name  string
+		input []interface{}
+		want  []string
+	}{
+		{"tenant only", []interface{}{"tenant"}, []string{"bot"}},
+		{"user only", []interface{}{"user"}, []string{"user"}},
+		{"tenant then user", []interface{}{"tenant", "user"}, []string{"bot", "user"}},
+		{"user then tenant", []interface{}{"user", "tenant"}, []string{"bot", "user"}},
+		{"deduped", []interface{}{"tenant", "tenant", "user"}, []string{"bot", "user"}},
+		{"empty", []interface{}{}, []string{}},
+		{"nil", nil, []string{}},
+		{"unknown skipped", []interface{}{"user", "admin"}, []string{"user"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := convertAccessTokens(tt.input)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("got %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildMeta_FullFields(t *testing.T) {
+	// Synthesized method to avoid runtime variance from remote-cache overlay
+	// (which strips `risk` from merged services). All other field semantics
+	// match the real im.images.create entry in meta_data.json.
+	method := map[string]interface{}{
+		"risk":   "write",
+		"danger": true,
+		"scopes": []interface{}{
+			"im:resource:upload",
+			"im:resource",
+		},
+		"accessTokens": []interface{}{"tenant"},
+		"docUrl":       "https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create",
+	}
+	m := buildMeta(method)
+
+	if m.EnvelopeVersion != "1.0" {
+		t.Errorf("EnvelopeVersion = %q", m.EnvelopeVersion)
+	}
+	if m.Risk != "write" {
+		t.Errorf("Risk = %q, want \"write\"", m.Risk)
+	}
+	if !m.Danger {
+		t.Errorf("Danger = false, want true")
+	}
+	if !reflect.DeepEqual(m.AccessTokens, []string{"bot"}) {
+		t.Errorf("AccessTokens = %v, want [bot]", m.AccessTokens)
+	}
+	if m.DocURL == "" {
+		t.Errorf("DocURL should be present for im.images.create")
+	}
+	if !reflect.DeepEqual(m.Scopes, []string{"im:resource:upload", "im:resource"}) {
+		t.Errorf("Scopes = %v, want [im:resource:upload, im:resource] (meta_data natural order)", m.Scopes)
+	}
+	if m.RequiredScopes == nil {
+		t.Errorf("RequiredScopes should be empty slice, not nil")
+	}
+	if len(m.RequiredScopes) != 0 {
+		t.Errorf("RequiredScopes should be empty for this method, got %v", m.RequiredScopes)
+	}
+	if m.Affordance != nil {
+		t.Errorf("Affordance must be nil when method has no affordance field, got %+v", m.Affordance)
+	}
+}
+
+func TestBuildMeta_MissingRiskDefaultsToRead(t *testing.T) {
+	method := map[string]interface{}{
+		"scopes":       []interface{}{"x"},
+		"accessTokens": []interface{}{"user"},
+		// no risk field
+	}
+	m := buildMeta(method)
+	if m.Risk != "read" {
+		t.Errorf("Risk = %q, want \"read\" (default for missing risk)", m.Risk)
+	}
+}
+
+func TestBuildMeta_RequiredScopesPresent(t *testing.T) {
+	method := loadMethodFromRegistry(t, "mail", []string{"user_mailbox", "messages"}, "get")
+	m := buildMeta(method)
+	if len(m.RequiredScopes) == 0 {
+		t.Errorf("RequiredScopes should be non-empty for mail.user_mailbox.messages.get")
+	}
+}
+
+func TestParseAffordance_NilOrEmpty(t *testing.T) {
+	cases := []struct {
+		name string
+		raw  interface{}
+	}{
+		{"nil", nil},
+		{"empty object", map[string]interface{}{}},
+		{"all-five-empty-arrays", map[string]interface{}{
+			"use_when":        []interface{}{},
+			"do_not_use_when": []interface{}{},
+			"prerequisites":   []interface{}{},
+			"examples":        []interface{}{},
+			"related":         []interface{}{},
+		}},
+		{"malformed (string)", "not an object"},
+		{"malformed (number)", 42},
+		{"malformed (nested type mismatch)", map[string]interface{}{
+			"examples": "should be a list, not a string",
+		}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := parseAffordance(c.raw); got != nil {
+				t.Errorf("parseAffordance(%v) = %+v, want nil", c.raw, got)
+			}
+		})
+	}
+}
+
+func TestParseAffordance_FullPopulated(t *testing.T) {
+	raw := map[string]interface{}{
+		"use_when":        []interface{}{"需要拿到当前用户的主日历 ID"},
+		"do_not_use_when": []interface{}{"已知具体某一个非主日历的 calendar_id"},
+		"prerequisites":   []interface{}{"user 身份登录"},
+		"examples": []interface{}{
+			map[string]interface{}{"title": "获取主日历", "input": map[string]interface{}{}},
+		},
+		"related": []interface{}{"calendars.list"},
+	}
+	a := parseAffordance(raw)
+	if a == nil {
+		t.Fatal("parseAffordance returned nil, want populated")
+	}
+	if len(a.UseWhen) != 1 || a.UseWhen[0] != "需要拿到当前用户的主日历 ID" {
+		t.Errorf("UseWhen = %v", a.UseWhen)
+	}
+	if len(a.Examples) != 1 || a.Examples[0].Title != "获取主日历" {
+		t.Errorf("Examples = %+v", a.Examples)
+	}
+	if len(a.Related) != 1 || a.Related[0] != "calendars.list" {
+		t.Errorf("Related = %v", a.Related)
+	}
+}
+
+func TestBuildMeta_AffordanceFromMethod(t *testing.T) {
+	method := map[string]interface{}{
+		"scopes":       []interface{}{"x"},
+		"accessTokens": []interface{}{"user"},
+		"risk":         "read",
+		"affordance": map[string]interface{}{
+			"use_when": []interface{}{"trigger"},
+		},
+	}
+	m := buildMeta(method)
+	if m.Affordance == nil {
+		t.Fatal("Affordance should be populated from method[\"affordance\"]")
+	}
+	if len(m.Affordance.UseWhen) != 1 || m.Affordance.UseWhen[0] != "trigger" {
+		t.Errorf("UseWhen = %v", m.Affordance.UseWhen)
+	}
+}
+
+func TestBuildMeta_MissingDocURLOmitted(t *testing.T) {
+	method := map[string]interface{}{
+		"scopes":       []interface{}{"x"},
+		"accessTokens": []interface{}{"user"},
+		"risk":         "read",
+		// no docUrl
+	}
+	m := buildMeta(method)
+	if m.DocURL != "" {
+		t.Errorf("DocURL = %q, want empty (will be omitempty)", m.DocURL)
+	}
+	// Verify JSON serialization omits doc_url
+	b, _ := json.Marshal(m)
+	if strings.Contains(string(b), "doc_url") {
+		t.Errorf("doc_url should be omitted from JSON, got: %s", b)
+	}
+}
+
+func TestBuildOutputSchema_EmptyResponseBody(t *testing.T) {
+	// 装配器对空 responseBody 应生成 properties = {} （不 nil）
+	method := map[string]interface{}{}
+	currentMethodOrder = nil
+	os := buildOutputSchema(method)
+	if os.Type != "object" {
+		t.Errorf("Type = %q, want \"object\"", os.Type)
+	}
+	if os.Properties == nil {
+		t.Fatal("Properties is nil, want empty OrderedProps")
+	}
+	if len(os.Properties.Order) != 0 {
+		t.Errorf("Properties.Order should be empty, got %v", os.Properties.Order)
+	}
+}
+
+func TestAssembleEnvelope_ReactionsList_FullStructure(t *testing.T) {
+	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	env := AssembleEnvelope("im", []string{"reactions"}, "list", method)
+
+	if env.Name != "im reactions list" {
+		t.Errorf("Name = %q, want \"im reactions list\"", env.Name)
+	}
+	if env.Description == "" {
+		t.Errorf("Description should not be empty for im.reactions.list")
+	}
+	if env.InputSchema == nil || env.OutputSchema == nil || env.Meta == nil {
+		t.Fatal("InputSchema/OutputSchema/Meta must all be non-nil")
+	}
+	if env.Meta.EnvelopeVersion != "1.0" {
+		t.Errorf("Meta.EnvelopeVersion = %q", env.Meta.EnvelopeVersion)
+	}
+}
+
+func TestAssembleEnvelope_NestedResource_NameJoinedWithSpaces(t *testing.T) {
+	// im.chat.members.create — resource path is one element "chat.members" with
+	// an internal dot. Substituted from plan's `bots` because remote-cache
+	// overlay strips `bots` from the loaded method map on this environment;
+	// the assertion is about name joining, not method specifics.
+	method := loadMethodFromRegistry(t, "im", []string{"chat.members"}, "create")
+	env := AssembleEnvelope("im", []string{"chat.members"}, "create", method)
+	// chat.members resourcePath stays as one element in the slice with a dot;
+	// name should split it to "im chat.members create" — we keep the dot as-is
+	// inside the resource segment to round-trip with completion logic.
+	if env.Name != "im chat.members create" {
+		t.Errorf("Name = %q, want \"im chat.members create\"", env.Name)
+	}
+}
+
+func TestAssembleEnvelope_JSONIsStable(t *testing.T) {
+	// Assemble twice; JSON output must be byte-identical (determinism).
+	method := loadMethodFromRegistry(t, "im", []string{"reactions"}, "list")
+	a := AssembleEnvelope("im", []string{"reactions"}, "list", method)
+	b := AssembleEnvelope("im", []string{"reactions"}, "list", method)
+	ja, _ := json.MarshalIndent(a, "", "  ")
+	jb, _ := json.MarshalIndent(b, "", "  ")
+	if string(ja) != string(jb) {
+		t.Errorf("envelope assembly is non-deterministic:\nfirst:\n%s\nsecond:\n%s", ja, jb)
+	}
+}
+
+func TestAssembleService_Im(t *testing.T) {
+	spec := registry.LoadFromMeta("im")
+	envs := AssembleService("im", spec, nil)
+	if len(envs) == 0 {
+		t.Fatal("expected non-empty envelopes for service im")
+	}
+	// Every envelope.Name starts with "im "
+	for _, e := range envs {
+		if !strings.HasPrefix(e.Name, "im ") {
+			t.Errorf("envelope name %q does not start with \"im \"", e.Name)
+		}
+	}
+	// Sorted by name
+	for i := 1; i < len(envs); i++ {
+		if envs[i-1].Name > envs[i].Name {
+			t.Errorf("envelopes not sorted by name at idx %d: %q > %q", i, envs[i-1].Name, envs[i].Name)
+		}
+	}
+}
+
+func TestAssembleService_FilterByAccessToken(t *testing.T) {
+	spec := registry.LoadFromMeta("im")
+	// Filter to bot-only (--as bot, which corresponds to "tenant")
+	envs := AssembleService("im", spec, func(method map[string]interface{}) bool {
+		tokens, _ := method["accessTokens"].([]interface{})
+		for _, t := range tokens {
+			if s, _ := t.(string); s == "tenant" {
+				return true
+			}
+		}
+		return false
+	})
+	// Every envelope's _meta.access_tokens must contain "bot"
+	for _, e := range envs {
+		found := false
+		for _, t := range e.Meta.AccessTokens {
+			if t == "bot" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("envelope %q does not declare bot access", e.Name)
+		}
+	}
+}
+
+func TestAssembleAll_AtLeast193(t *testing.T) {
+	envs := AssembleAll(nil)
+	// Envelope assembly is overlay-independent (Task 17b): AssembleAll walks the
+	// embedded meta_data.json directly, so the count is stable across machines.
+	if len(envs) < 193 {
+		t.Errorf("AssembleAll returned %d envelopes, expected >= 193", len(envs))
+	}
+	// Spot check: im reactions list should be present
+	found := false
+	for _, e := range envs {
+		if e.Name == "im reactions list" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("im reactions list not found in AssembleAll output")
+	}
+}
+
+// loadMethodFromRegistry is a test helper that pulls one method's spec from the
+// real embedded meta_data.json via the registry package.
+func loadMethodFromRegistry(t *testing.T, service string, resourcePath []string, methodName string) map[string]interface{} {
+	t.Helper()
+	spec := registry.LoadFromMeta(service)
+	if spec == nil {
+		t.Fatalf("service %q not found in registry", service)
+	}
+	resources, _ := spec["resources"].(map[string]interface{})
+	resKey := strings.Join(resourcePath, ".")
+	res, ok := resources[resKey].(map[string]interface{})
+	if !ok {
+		t.Fatalf("resource %q.%s not found", service, resKey)
+	}
+	methods, _ := res["methods"].(map[string]interface{})
+	m, ok := methods[methodName].(map[string]interface{})
+	if !ok {
+		t.Fatalf("method %q.%s.%s not found", service, resKey, methodName)
+	}
+	return m
+}
--- a/internal/schema/lint.go
+++ b/internal/schema/lint.go
@@ -0,0 +1,233 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+var validJSONSchemaTypes = map[string]bool{
+	"string":  true,
+	"integer": true,
+	"number":  true,
+	"boolean": true,
+	"array":   true,
+	"object":  true,
+}
+
+var validAccessTokens = map[string]bool{
+	"user": true,
+	"bot":  true,
+}
+
+// lintEnvelope runs L1-L3 checks and returns a list of errors. Empty slice
+// means the envelope is compliant.
+func lintEnvelope(env Envelope) []error {
+	var errs []error
+
+	// ---- L1: structural ----
+	if env.Name == "" {
+		errs = append(errs, errors.New("L1: name must not be empty"))
+	}
+	if env.InputSchema == nil {
+		errs = append(errs, errors.New("L1: inputSchema must not be nil"))
+	} else {
+		if env.InputSchema.Type != "object" {
+			errs = append(errs, fmt.Errorf("L1: inputSchema.type = %q, want \"object\"", env.InputSchema.Type))
+		}
+		if env.InputSchema.Properties == nil {
+			errs = append(errs, errors.New("L1: inputSchema.properties must not be nil"))
+		}
+	}
+	if env.OutputSchema == nil {
+		errs = append(errs, errors.New("L1: outputSchema must not be nil"))
+	} else {
+		if env.OutputSchema.Type != "object" {
+			errs = append(errs, fmt.Errorf("L1: outputSchema.type = %q, want \"object\"", env.OutputSchema.Type))
+		}
+	}
+	if env.Meta == nil {
+		errs = append(errs, errors.New("L1: _meta must not be nil"))
+		// Cannot continue meta-dependent checks
+		return errs
+	}
+	if env.Meta.EnvelopeVersion != "1.0" {
+		errs = append(errs, fmt.Errorf("L1: _meta.envelope_version = %q, want \"1.0\"", env.Meta.EnvelopeVersion))
+	}
+
+	// L1: validate every Property type recursively
+	if env.InputSchema != nil && env.InputSchema.Properties != nil {
+		validatePropertyTypes(env.InputSchema.Properties, &errs)
+	}
+	if env.OutputSchema != nil && env.OutputSchema.Properties != nil {
+		validatePropertyTypes(env.OutputSchema.Properties, &errs)
+	}
+
+	// ---- L2: type-level consistency ----
+	if env.InputSchema != nil && env.InputSchema.Properties != nil {
+		// Walk the whole property tree so format/min-max checks reach leaf
+		// fields nested under the params/data wrapper.
+		walkForL2(env.InputSchema.Properties, &errs)
+		// Top-level required keys must exist in top-level properties.
+		for _, r := range env.InputSchema.Required {
+			if _, ok := env.InputSchema.Properties.Map[r]; !ok {
+				errs = append(errs, fmt.Errorf("L2: required key %q not found in properties", r))
+			}
+		}
+	}
+
+	// ---- L3: cross-field self-consistency ----
+	dangerExpected := env.Meta.Risk == cmdutil.RiskWrite || env.Meta.Risk == cmdutil.RiskHighRiskWrite
+	if env.Meta.Danger != dangerExpected {
+		errs = append(errs, fmt.Errorf("L3: _meta.danger=%v inconsistent with risk=%q", env.Meta.Danger, env.Meta.Risk))
+	}
+
+	// `yes` lives at inputSchema.properties.yes (sibling of params/data),
+	// injected only for risk == RiskHighRiskWrite.
+	hasYes := false
+	if env.InputSchema != nil && env.InputSchema.Properties != nil {
+		_, hasYes = env.InputSchema.Properties.Map["yes"]
+	}
+	wantYes := env.Meta.Risk == cmdutil.RiskHighRiskWrite
+	if hasYes != wantYes {
+		errs = append(errs, fmt.Errorf("L3: inputSchema `yes` property=%v inconsistent with risk=%q", hasYes, env.Meta.Risk))
+	}
+
+	if len(env.Meta.AccessTokens) == 0 {
+		errs = append(errs, errors.New("L3: _meta.access_tokens must not be empty"))
+	}
+	for _, t := range env.Meta.AccessTokens {
+		if !validAccessTokens[t] {
+			errs = append(errs, fmt.Errorf("L3: _meta.access_tokens contains invalid value %q (allowed: user, bot)", t))
+		}
+	}
+
+	return errs
+}
+
+// walkForL2 recursively applies per-field L2 checks (format:binary on
+// non-string; minimum>=maximum) plus the sub-object required-exists invariant.
+// Required only matters on object-typed Properties (e.g. the params / data
+// wrappers); leaf scalars ignore it.
+func walkForL2(props *OrderedProps, errs *[]error) {
+	if props == nil {
+		return
+	}
+	for _, k := range props.Order {
+		p := props.Map[k]
+		if p.Format == "binary" && p.Type != "string" {
+			*errs = append(*errs, fmt.Errorf("L2: field %q has format: binary but type = %q (want string)", k, p.Type))
+		}
+		if p.Minimum != nil && p.Maximum != nil && *p.Minimum >= *p.Maximum {
+			*errs = append(*errs, fmt.Errorf("L2: field %q minimum (%v) >= maximum (%v)", k, *p.Minimum, *p.Maximum))
+		}
+		if len(p.Required) > 0 && p.Properties != nil {
+			for _, r := range p.Required {
+				if _, ok := p.Properties.Map[r]; !ok {
+					*errs = append(*errs, fmt.Errorf("L2: required key %q in %q not found in its properties", r, k))
+				}
+			}
+		}
+		if p.Properties != nil {
+			walkForL2(p.Properties, errs)
+		}
+	}
+}
+
+// validatePropertyTypes walks an OrderedProps tree and asserts:
+//   - every Property.Type is in validJSONSchemaTypes (or empty for nested objects with only properties)
+//   - array Properties have Items
+//
+// Errors are appended to *errs.
+func validatePropertyTypes(props *OrderedProps, errs *[]error) {
+	if props == nil {
+		return
+	}
+	for _, k := range props.Order {
+		p := props.Map[k]
+		if p.Type != "" && !validJSONSchemaTypes[p.Type] {
+			*errs = append(*errs, fmt.Errorf("L1: property %q has invalid type %q", k, p.Type))
+		}
+		if p.Type == "array" && p.Items == nil {
+			*errs = append(*errs, fmt.Errorf("L1: array property %q missing items", k))
+		}
+		if p.Properties != nil {
+			validatePropertyTypes(p.Properties, errs)
+		}
+		// Validate the array-element schema itself, not only its child
+		// properties — a primitive element with an invalid type (e.g.
+		// `items.type = "list"`) would otherwise slip past lint.
+		if p.Items != nil {
+			validateItemSchema(k, p.Items, errs)
+		}
+	}
+}
+
+// validateItemSchema checks a single array element schema for invalid types,
+// then recurses into any further nested properties/items.
+func validateItemSchema(parentKey string, item *Property, errs *[]error) {
+	if item.Type != "" && !validJSONSchemaTypes[item.Type] {
+		*errs = append(*errs, fmt.Errorf("L1: array property %q items has invalid type %q", parentKey, item.Type))
+	}
+	if item.Type == "array" && item.Items == nil {
+		*errs = append(*errs, fmt.Errorf("L1: array property %q items (nested array) missing items", parentKey))
+	}
+	if item.Properties != nil {
+		validatePropertyTypes(item.Properties, errs)
+	}
+	if item.Items != nil {
+		validateItemSchema(parentKey, item.Items, errs)
+	}
+}
+
+// coverageBaseline is the per-metric warn threshold for L4 coverage checks.
+// If the measured rate drops below the baseline, t.Logf emits a warning but
+// does NOT fail the test. Adjust these constants upward as meta_data quality
+// improves over time.
+var coverageBaseline = map[string]float64{
+	"description": 0.99,
+	"scopes":      1.00,
+	"doc_url":     0.98,
+	"risk":        0.96,
+}
+
+// measureCoverage returns the non-empty rate for each tracked metric.
+func measureCoverage(envs []Envelope) map[string]float64 {
+	if len(envs) == 0 {
+		return map[string]float64{
+			"description": 0,
+			"scopes":      0,
+			"doc_url":     0,
+			"risk":        0,
+		}
+	}
+	total := float64(len(envs))
+	var descNonEmpty, scopesNonEmpty, docURLNonEmpty, riskNonEmpty float64
+	for _, e := range envs {
+		if e.Description != "" {
+			descNonEmpty++
+		}
+		if e.Meta == nil {
+			continue
+		}
+		if len(e.Meta.Scopes) > 0 {
+			scopesNonEmpty++
+		}
+		if e.Meta.DocURL != "" {
+			docURLNonEmpty++
+		}
+		if e.Meta.Risk != "" {
+			riskNonEmpty++
+		}
+	}
+	return map[string]float64{
+		"description": descNonEmpty / total,
+		"scopes":      scopesNonEmpty / total,
+		"doc_url":     docURLNonEmpty / total,
+		"risk":        riskNonEmpty / total,
+	}
+}
--- a/internal/schema/lint_test.go
+++ b/internal/schema/lint_test.go
@@ -0,0 +1,379 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/registry"
+)
+
+// validEnvelope builds a baseline valid envelope used as a starting point in
+// negative tests below.
+func validEnvelope() Envelope {
+	props := &OrderedProps{Map: map[string]Property{}}
+	return Envelope{
+		Name:        "x y z",
+		Description: "ok",
+		InputSchema: &InputSchema{
+			Type:       "object",
+			Properties: props,
+		},
+		OutputSchema: &OutputSchema{
+			Type:       "object",
+			Properties: &OrderedProps{Map: map[string]Property{}},
+		},
+		Meta: &Meta{
+			EnvelopeVersion: "1.0",
+			AccessTokens:    []string{"user"},
+			Risk:            "read",
+			Danger:          false,
+		},
+	}
+}
+
+func TestLintEnvelope_Valid(t *testing.T) {
+	env := validEnvelope()
+	errs := lintEnvelope(env)
+	if len(errs) != 0 {
+		t.Errorf("expected no errors, got: %v", errs)
+	}
+}
+
+func TestLintEnvelope_L1_StructuralChecks(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func(*Envelope)
+		wantSub string
+	}{
+		{
+			name:    "empty name",
+			mutate:  func(e *Envelope) { e.Name = "" },
+			wantSub: "name",
+		},
+		{
+			name:    "nil InputSchema",
+			mutate:  func(e *Envelope) { e.InputSchema = nil },
+			wantSub: "inputSchema",
+		},
+		{
+			name:    "inputSchema type not object",
+			mutate:  func(e *Envelope) { e.InputSchema.Type = "string" },
+			wantSub: "inputSchema.type",
+		},
+		{
+			name:    "nil OutputSchema",
+			mutate:  func(e *Envelope) { e.OutputSchema = nil },
+			wantSub: "outputSchema",
+		},
+		{
+			name:    "nil Meta",
+			mutate:  func(e *Envelope) { e.Meta = nil },
+			wantSub: "_meta",
+		},
+		{
+			name:    "wrong envelope version",
+			mutate:  func(e *Envelope) { e.Meta.EnvelopeVersion = "0.9" },
+			wantSub: "envelope_version",
+		},
+		{
+			name: "invalid property type",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"x"}
+				e.InputSchema.Properties.Map["x"] = Property{Type: "unknown_type"}
+			},
+			wantSub: "invalid type",
+		},
+		{
+			name: "array missing items",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"x"}
+				e.InputSchema.Properties.Map["x"] = Property{Type: "array"} // no Items
+			},
+			wantSub: "items",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			env := validEnvelope()
+			tt.mutate(&env)
+			errs := lintEnvelope(env)
+			if len(errs) == 0 {
+				t.Fatalf("expected lint error, got none")
+			}
+			found := false
+			for _, e := range errs {
+				if strings.Contains(e.Error(), tt.wantSub) {
+					found = true
+					break
+				}
+			}
+			if !found {
+				t.Errorf("expected error containing %q, got: %v", tt.wantSub, errs)
+			}
+		})
+	}
+}
+
+func TestLintEnvelope_L2_TypeChecks(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func(*Envelope)
+		wantSub string
+	}{
+		{
+			name: "format binary on non-string",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"f"}
+				e.InputSchema.Properties.Map["f"] = Property{Type: "integer", Format: "binary"}
+			},
+			wantSub: "format: binary",
+		},
+		{
+			name: "required key not in properties",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Required = []string{"nonexistent"}
+			},
+			wantSub: "required",
+		},
+		{
+			name: "minimum >= maximum",
+			mutate: func(e *Envelope) {
+				min, max := 50.0, 10.0
+				e.InputSchema.Properties.Order = []string{"n"}
+				e.InputSchema.Properties.Map["n"] = Property{Type: "integer", Minimum: &min, Maximum: &max}
+			},
+			wantSub: "minimum",
+		},
+		{
+			// Regression guard: walkForL2 must recurse into the params/data
+			// sub-objects introduced by the 4-bucket inputSchema, not only the
+			// top-level Properties map.
+			name: "format binary on non-string inside params sub-object",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"params"}
+				e.InputSchema.Properties.Map["params"] = Property{
+					Type: "object",
+					Properties: &OrderedProps{
+						Order: []string{"id"},
+						Map: map[string]Property{
+							"id": {Type: "integer", Format: "binary"}, // wrong: binary on integer
+						},
+					},
+				}
+			},
+			wantSub: "format: binary",
+		},
+		{
+			name: "sub-object required references missing property",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"data"}
+				e.InputSchema.Properties.Map["data"] = Property{
+					Type:     "object",
+					Required: []string{"ghost"}, // not in properties below
+					Properties: &OrderedProps{
+						Order: []string{"real"},
+						Map:   map[string]Property{"real": {Type: "string"}},
+					},
+				}
+			},
+			wantSub: "ghost",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			env := validEnvelope()
+			tt.mutate(&env)
+			errs := lintEnvelope(env)
+			if len(errs) == 0 {
+				t.Fatalf("expected lint error, got none")
+			}
+			found := false
+			for _, e := range errs {
+				if strings.Contains(e.Error(), tt.wantSub) {
+					found = true
+					break
+				}
+			}
+			if !found {
+				t.Errorf("expected error containing %q, got: %v", tt.wantSub, errs)
+			}
+		})
+	}
+}
+
+func TestLintEnvelope_L3_CrossFieldChecks(t *testing.T) {
+	tests := []struct {
+		name    string
+		mutate  func(*Envelope)
+		wantSub string
+	}{
+		{
+			name: "danger true but risk read",
+			mutate: func(e *Envelope) {
+				e.Meta.Danger = true
+				e.Meta.Risk = "read"
+			},
+			wantSub: "danger",
+		},
+		{
+			name: "high-risk-write without yes",
+			mutate: func(e *Envelope) {
+				e.Meta.Risk = "high-risk-write"
+				e.Meta.Danger = true
+				// no yes injection
+			},
+			wantSub: "yes",
+		},
+		{
+			name: "yes injected but risk not high-risk-write",
+			mutate: func(e *Envelope) {
+				e.InputSchema.Properties.Order = []string{"yes"}
+				e.InputSchema.Properties.Map["yes"] = Property{Type: "boolean"}
+			},
+			wantSub: "yes",
+		},
+		{
+			name: "empty access_tokens",
+			mutate: func(e *Envelope) {
+				e.Meta.AccessTokens = []string{}
+			},
+			wantSub: "access_tokens",
+		},
+		{
+			name: "invalid access_token value",
+			mutate: func(e *Envelope) {
+				e.Meta.AccessTokens = []string{"admin"}
+			},
+			wantSub: "access_tokens",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			env := validEnvelope()
+			tt.mutate(&env)
+			errs := lintEnvelope(env)
+			if len(errs) == 0 {
+				t.Fatalf("expected lint error, got none")
+			}
+			found := false
+			for _, e := range errs {
+				if strings.Contains(e.Error(), tt.wantSub) {
+					found = true
+					break
+				}
+			}
+			if !found {
+				t.Errorf("expected error containing %q, got: %v", tt.wantSub, errs)
+			}
+		})
+	}
+}
+
+func TestMeasureCoverage_Counts(t *testing.T) {
+	envs := []Envelope{
+		{Description: "ok", Meta: &Meta{Scopes: []string{"s"}, Risk: "read", DocURL: "http://x"}},
+		{Description: "", Meta: &Meta{Scopes: []string{}, Risk: "", DocURL: ""}},
+		{Description: "ok2", Meta: &Meta{Scopes: []string{"s"}, Risk: "write", DocURL: "http://y"}},
+	}
+	c := measureCoverage(envs)
+	// 2/3 have non-empty description = ~0.667
+	if c["description"] < 0.66 || c["description"] > 0.67 {
+		t.Errorf("description coverage = %v, want ~0.667", c["description"])
+	}
+	// 2/3 have non-empty scopes
+	if c["scopes"] < 0.66 || c["scopes"] > 0.67 {
+		t.Errorf("scopes coverage = %v, want ~0.667", c["scopes"])
+	}
+	// 2/3 have doc_url
+	if c["doc_url"] < 0.66 || c["doc_url"] > 0.67 {
+		t.Errorf("doc_url coverage = %v, want ~0.667", c["doc_url"])
+	}
+	// 2/3 have non-empty risk (but our builder always fills risk with "read" default — this test uses raw envs)
+	if c["risk"] < 0.66 || c["risk"] > 0.67 {
+		t.Errorf("risk coverage = %v, want ~0.667", c["risk"])
+	}
+}
+
+// isKnownDataInconsistency returns true for lint errors that originate from
+// real meta_data quality issues we still have to ship around in PR-1. With
+// Task 17b the assembler walks embedded data only, so overlay-induced
+// inconsistencies (risk-stripping) no longer appear; only the true embedded
+// meta_data data-quality patterns remain.
+//
+// As meta_data quality improves this filter should be tightened/removed so
+// TestAllEnvelopesPass becomes a hard gate again.
+func isKnownDataInconsistency(msg string) bool {
+	switch {
+	case strings.Contains(msg, `L3: _meta.danger=false inconsistent with risk="write"`):
+		// Embedded meta_data has ~7 envelopes (e.g. attendance.user_tasks.query,
+		// drive.user.subscription, mail.user_mailbox.event.subscribe) where
+		// `risk="write"` but `danger` is missing (defaults to false). Needs a
+		// meta_data fix to set danger=true on these write methods.
+		return true
+	case strings.Contains(msg, `L3: _meta.danger=true inconsistent with risk="read"`):
+		// Embedded meta_data has ~9 envelopes (e.g. calendar.events.search_event,
+		// drive.metas.batch_query, mail.user_mailbox.templates.create) where
+		// `danger=true` but `risk` is missing (defaults to "read"). Needs a
+		// meta_data fix to set the proper risk level on these methods.
+		return true
+	case strings.Contains(msg, "L2: field") && strings.Contains(msg, "minimum") && strings.Contains(msg, "maximum"):
+		// meta_data sets min == max on some fields (e.g.
+		// mail.user_mailbox.event.subscribe.event_type), which the lint reads
+		// as min >= max. Real fix is in meta_data.
+		return true
+	}
+	return false
+}
+
+func TestAllEnvelopesPass(t *testing.T) {
+	failCount := 0
+	knownWarnings := 0
+	knownEnvelopes := map[string]bool{}
+	// Use embedded data only so the gate is deterministic across machines
+	// (matches Task 17b: envelope assembly is overlay-independent).
+	for _, svc := range registry.EmbeddedServiceNames() {
+		spec := registry.EmbeddedSpec(svc)
+		envs := AssembleService(svc, spec, nil)
+		for _, env := range envs {
+			errs := lintEnvelope(env)
+			if len(errs) == 0 {
+				continue
+			}
+			var realErrs []error
+			for _, e := range errs {
+				if isKnownDataInconsistency(e.Error()) {
+					t.Logf("env %s skipped: known data-level inconsistency: %v", env.Name, e)
+					knownWarnings++
+					knownEnvelopes[env.Name] = true
+					continue
+				}
+				realErrs = append(realErrs, e)
+			}
+			if len(realErrs) > 0 {
+				for _, e := range realErrs {
+					t.Errorf("%s: %v", env.Name, e)
+				}
+				failCount++
+			}
+		}
+	}
+	t.Logf("L1-L3 known data-level inconsistencies: %d warnings across %d envelopes (danger/risk mismatch + min==max)", knownWarnings, len(knownEnvelopes))
+	if failCount > 0 {
+		t.Fatalf("%d envelopes failed L1-L3 lint with non-data-level errors", failCount)
+	}
+
+	// L4 coverage report (warn-only via t.Logf)
+	all := AssembleAll(nil)
+	c := measureCoverage(all)
+	for metric, rate := range c {
+		baseline := coverageBaseline[metric]
+		if rate < baseline {
+			t.Logf("L4 coverage warn: %s = %.1f%% (baseline: %.1f%%)", metric, rate*100, baseline*100)
+		} else {
+			t.Logf("L4 coverage ok:   %s = %.1f%% (baseline: %.1f%%)", metric, rate*100, baseline*100)
+		}
+	}
+}
--- a/internal/schema/path.go
+++ b/internal/schema/path.go
@@ -0,0 +1,30 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import "strings"
+
+// ParsePath normalizes the positional arguments of `lark-cli schema` into a
+// slice of path segments. It accepts two equivalent forms:
+//
+//	lark-cli schema im.messages.reply  -> single arg, split on "."
+//	lark-cli schema im messages reply  -> multiple args, used as-is
+//	lark-cli schema "im chat.members bots" is NOT a supported form; quote
+//	arguments individually if your shell needs it. Nested resources keep their
+//	internal dots (e.g. "chat.members").
+//
+// Returns nil for zero args (bare invocation).
+func ParsePath(args []string) []string {
+	switch len(args) {
+	case 0:
+		return nil
+	case 1:
+		if strings.Contains(args[0], ".") {
+			return strings.Split(args[0], ".")
+		}
+		return []string{args[0]}
+	default:
+		return args
+	}
+}
--- a/internal/schema/path_test.go
+++ b/internal/schema/path_test.go
@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestParsePath(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want []string
+	}{
+		{"empty args -> nil", nil, nil},
+		{"empty slice -> nil", []string{}, nil},
+		{"single dotted", []string{"im.messages.reply"}, []string{"im", "messages", "reply"}},
+		{"single no-dot", []string{"im"}, []string{"im"}},
+		{"multi args", []string{"im", "messages", "reply"}, []string{"im", "messages", "reply"}},
+		{"two args", []string{"im", "messages"}, []string{"im", "messages"}},
+		{"nested resource dotted", []string{"im.chat.members.bots"}, []string{"im", "chat", "members", "bots"}},
+		{"nested resource space form", []string{"im", "chat.members", "bots"}, []string{"im", "chat.members", "bots"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ParsePath(tt.args)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("ParsePath(%v) = %v, want %v", tt.args, got, tt.want)
+			}
+		})
+	}
+}
--- a/internal/schema/types.go
+++ b/internal/schema/types.go
@@ -0,0 +1,163 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"sort"
+)
+
+// Envelope is the MCP Tool spec contract for a single API method command.
+type Envelope struct {
+	Name         string        `json:"name"`
+	Description  string        `json:"description"`
+	InputSchema  *InputSchema  `json:"inputSchema"`
+	OutputSchema *OutputSchema `json:"outputSchema"`
+	Meta         *Meta         `json:"_meta"`
+}
+
+// InputSchema is JSON Schema Draft 2020-12 flattened.
+//
+// Required is intentionally rendered (no omitempty) so the envelope shape
+// stays stable for AI consumers — an empty []string means "no required
+// fields" rather than "schema is missing the field".
+type InputSchema struct {
+	Type       string        `json:"type"`
+	Required   []string      `json:"required"`
+	Properties *OrderedProps `json:"properties"`
+}
+
+// OutputSchema wraps responseBody into a JSON Schema object.
+type OutputSchema struct {
+	Type       string        `json:"type"`
+	Properties *OrderedProps `json:"properties"`
+}
+
+// Property is one field's JSON Schema shape, recursive.
+//
+// Required is used when Property describes a nested object (e.g. the
+// "params" / "data" sub-objects inside inputSchema): it lists which keys
+// inside that object's Properties are mandatory. Leaf fields ignore it.
+type Property struct {
+	Type        string        `json:"type,omitempty"`
+	Description string        `json:"description,omitempty"`
+	Enum        []interface{} `json:"enum,omitempty"`
+	Default     interface{}   `json:"default,omitempty"`
+	Example     interface{}   `json:"example,omitempty"`
+	Minimum     *float64      `json:"minimum,omitempty"`
+	Maximum     *float64      `json:"maximum,omitempty"`
+	Format      string        `json:"format,omitempty"`
+	Required    []string      `json:"required,omitempty"`
+	Properties  *OrderedProps `json:"properties,omitempty"`
+	Items       *Property     `json:"items,omitempty"`
+}
+
+// Meta is the Lark-specific extension namespace.
+type Meta struct {
+	EnvelopeVersion string      `json:"envelope_version"`
+	Scopes          []string    `json:"scopes"`
+	RequiredScopes  []string    `json:"required_scopes"`
+	AccessTokens    []string    `json:"access_tokens"`
+	Danger          bool        `json:"danger"`
+	Risk            string      `json:"risk"`
+	DocURL          string      `json:"doc_url,omitempty"`
+	Affordance      *Affordance `json:"affordance,omitempty"`
+}
+
+// Affordance is the hand-written overlay (PR-1 only defines the type, no YAML loaded).
+type Affordance struct {
+	UseWhen       []string         `json:"use_when,omitempty"`
+	DoNotUseWhen  []string         `json:"do_not_use_when,omitempty"`
+	Prerequisites []string         `json:"prerequisites,omitempty"`
+	Examples      []AffordanceCase `json:"examples,omitempty"`
+	Related       []string         `json:"related,omitempty"`
+}
+
+// AffordanceCase is one example entry.
+type AffordanceCase struct {
+	Title string                 `json:"title"`
+	Input map[string]interface{} `json:"input"`
+}
+
+// OrderedProps is map[string]Property with preserved key order on MarshalJSON.
+// It is used wherever JSON output must reflect meta_data.json's natural field
+// order rather than Go's default alphabetical map encoding.
+type OrderedProps struct {
+	Order []string
+	Map   map[string]Property
+}
+
+// MarshalJSON emits keys in Order, not alphabetical. If Order is empty but
+// Map has entries, fall back to alphabetical key order over Map so callers
+// that only populated Map (no explicit ordering) still see their fields.
+func (o *OrderedProps) MarshalJSON() ([]byte, error) {
+	if o == nil || (len(o.Order) == 0 && len(o.Map) == 0) {
+		return []byte("{}"), nil
+	}
+	keys := o.Order
+	if len(keys) == 0 {
+		keys = make([]string, 0, len(o.Map))
+		for k := range o.Map {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+	}
+	var buf bytes.Buffer
+	buf.WriteByte('{')
+	for i, k := range keys {
+		if i > 0 {
+			buf.WriteByte(',')
+		}
+		keyJSON, err := json.Marshal(k)
+		if err != nil {
+			return nil, fmt.Errorf("marshal key %q: %w", k, err)
+		}
+		buf.Write(keyJSON)
+		buf.WriteByte(':')
+		valJSON, err := json.Marshal(o.Map[k])
+		if err != nil {
+			return nil, fmt.Errorf("marshal value for %q: %w", k, err)
+		}
+		buf.Write(valJSON)
+	}
+	buf.WriteByte('}')
+	return buf.Bytes(), nil
+}
+
+// UnmarshalJSON parses an object preserving key order via json.Decoder.Token().
+// Used for round-tripping in tests (and future golden update flows).
+func (o *OrderedProps) UnmarshalJSON(data []byte) error {
+	dec := json.NewDecoder(bytes.NewReader(data))
+	tok, err := dec.Token()
+	if err != nil {
+		return err
+	}
+	if delim, ok := tok.(json.Delim); !ok || delim != '{' {
+		return fmt.Errorf("expected object, got %v", tok)
+	}
+	o.Order = nil
+	o.Map = make(map[string]Property)
+	for dec.More() {
+		keyTok, err := dec.Token()
+		if err != nil {
+			return err
+		}
+		key, ok := keyTok.(string)
+		if !ok {
+			return fmt.Errorf("expected string key, got %v", keyTok)
+		}
+		var prop Property
+		if err := dec.Decode(&prop); err != nil {
+			return err
+		}
+		o.Order = append(o.Order, key)
+		o.Map[key] = prop
+	}
+	if _, err := dec.Token(); err != nil {
+		return err
+	}
+	return nil
+}
--- a/internal/schema/types_test.go
+++ b/internal/schema/types_test.go
@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package schema
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// OrderedProps 在测试里验证：MarshalJSON 按 Order 切片顺序输出 key，跳过 Go map 默认字母序。
+func TestOrderedProps_MarshalJSON_PreservesOrder(t *testing.T) {
+	op := &OrderedProps{
+		Order: []string{"z_first", "a_second", "m_third"},
+		Map: map[string]Property{
+			"z_first":  {Type: "string"},
+			"a_second": {Type: "integer"},
+			"m_third":  {Type: "boolean"},
+		},
+	}
+	b, err := json.Marshal(op)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	got := string(b)
+	want := `{"z_first":{"type":"string"},"a_second":{"type":"integer"},"m_third":{"type":"boolean"}}`
+	if got != want {
+		t.Errorf("OrderedProps key order not preserved:\ngot:  %s\nwant: %s", got, want)
+	}
+}
+
+func TestOrderedProps_MarshalJSON_Empty(t *testing.T) {
+	op := &OrderedProps{Order: nil, Map: nil}
+	b, err := json.Marshal(op)
+	if err != nil {
+		t.Fatalf("Marshal failed: %v", err)
+	}
+	if string(b) != "{}" {
+		t.Errorf("empty OrderedProps should marshal to {}, got: %s", b)
+	}
+}
+
+func TestOrderedProps_UnmarshalJSON_RoundTrip(t *testing.T) {
+	in := []byte(`{"first":{"type":"string"},"second":{"type":"integer"}}`)
+	var op OrderedProps
+	if err := json.Unmarshal(in, &op); err != nil {
+		t.Fatalf("Unmarshal failed: %v", err)
+	}
+	if len(op.Order) != 2 {
+		t.Fatalf("expected 2 keys, got %d", len(op.Order))
+	}
+	if op.Order[0] != "first" || op.Order[1] != "second" {
+		t.Errorf("unmarshal lost order: got %v", op.Order)
+	}
+	if op.Map["first"].Type != "string" {
+		t.Errorf("first.type mismatch")
+	}
+}
--- a/shortcuts/doc/docs_fetch_v2.go
+++ b/shortcuts/doc/docs_fetch_v2.go
@@ -16,7 +16,7 @@ import (
 // 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", "text"}},
+		{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"}},
@@ -142,7 +142,7 @@ func buildReadOption(runtime *common.RuntimeContext) map[string]interface{} {
 	return ro
 }

-// validateFetchDetail 非 xml 格式（markdown/text）不承载 block_id 与样式属性，拒绝 with-ids/full。
+// validateFetchDetail 非 xml 格式（markdown）不承载 block_id 与样式属性，拒绝 with-ids/full。
 func validateFetchDetail(runtime *common.RuntimeContext) error {
 	format := strings.TrimSpace(runtime.Str("doc-format"))
 	detail := strings.TrimSpace(runtime.Str("detail"))
--- a/shortcuts/drive/drive_secure_label.go
+++ b/shortcuts/drive/drive_secure_label.go
@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	secureLabelReadScope   = "drive:file.meta.sec_label.read_only"
+	secureLabelUpdateScope = "docs:secure_label:write_only"
+)
+
+var secureLabelTypes = permApplyTypes
+
+// DriveSecureLabelList lists secure labels available to the current user.
+var DriveSecureLabelList = common.Shortcut{
+	Service:     "drive",
+	Command:     "+secure-label-list",
+	Description: "List secure labels available to the current user",
+	Risk:        "read",
+	Scopes:      []string{secureLabelReadScope},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "page-size", Type: "int", Default: "10", Desc: "page size, 1-10"},
+		{Name: "page-token", Desc: "pagination token from previous response"},
+		{Name: "lang", Desc: "label language", Enum: []string{"zh", "en", "ja"}},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		pageSize := runtime.Int("page-size")
+		if pageSize < 1 || pageSize > 10 {
+			return output.ErrValidation("--page-size must be between 1 and 10")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		return common.NewDryRunAPI().
+			Desc("List secure labels available to the current user").
+			GET("/open-apis/drive/v2/my_secure_labels").
+			Params(buildSecureLabelListParams(runtime))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		data, err := runtime.CallAPI("GET",
+			"/open-apis/drive/v2/my_secure_labels",
+			buildSecureLabelListParams(runtime),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutFormat(data, nil, nil)
+		return nil
+	},
+}
+
+// DriveSecureLabelUpdate updates the secure label on a Drive file/document.
+var DriveSecureLabelUpdate = common.Shortcut{
+	Service:     "drive",
+	Command:     "+secure-label-update",
+	Description: "Update the secure label on a Drive file or document",
+	Risk:        "write",
+	Scopes:      []string{secureLabelUpdateScope},
+	AuthTypes:   []string{"user"},
+	Flags: []common.Flag{
+		{Name: "token", Desc: "target file token or document URL (docx/sheets/base/file/wiki/doc/mindnote/slides)", Required: true},
+		{Name: "type", Desc: "target type; auto-inferred from URL when omitted", Enum: secureLabelTypes},
+		{Name: "label-id", Desc: "secure label ID to set", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, _, err := resolveSecureLabelTarget(runtime.Str("token"), runtime.Str("type"))
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, docType, err := resolveSecureLabelTarget(runtime.Str("token"), runtime.Str("type"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("Update Drive secure label").
+			PATCH("/open-apis/drive/v2/files/:file_token/secure_label").
+			Params(map[string]interface{}{"type": docType}).
+			Body(map[string]interface{}{"id": runtime.Str("label-id")}).
+			Set("file_token", token)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, docType, err := resolveSecureLabelTarget(runtime.Str("token"), runtime.Str("type"))
+		if err != nil {
+			return err
+		}
+		body := map[string]interface{}{"id": runtime.Str("label-id")}
+		data, err := runtime.CallAPI("PATCH",
+			fmt.Sprintf("/open-apis/drive/v2/files/%s/secure_label", validate.EncodePathSegment(token)),
+			map[string]interface{}{"type": docType},
+			body,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.Out(data, nil)
+		return nil
+	},
+}
+
+func buildSecureLabelListParams(runtime *common.RuntimeContext) map[string]interface{} {
+	params := map[string]interface{}{"page_size": runtime.Int("page-size")}
+	if pageToken := runtime.Str("page-token"); pageToken != "" {
+		params["page_token"] = pageToken
+	}
+	if lang := runtime.Str("lang"); lang != "" {
+		params["lang"] = lang
+	}
+	return params
+}
+
+func resolveSecureLabelTarget(raw, explicitType string) (token, docType string, err error) {
+	return resolvePermApplyTarget(raw, explicitType)
+}
--- a/shortcuts/drive/drive_secure_label_test.go
+++ b/shortcuts/drive/drive_secure_label_test.go
@@ -0,0 +1,164 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestDriveSecureLabelList_DryRun(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	err := mountAndRunDrive(t, DriveSecureLabelList, []string{
+		"+secure-label-list",
+		"--page-size", "5",
+		"--page-token", "page_1",
+		"--lang", "zh",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		"/open-apis/drive/v2/my_secure_labels",
+		`"GET"`,
+		`"page_size": 5`,
+		`"page_token": "page_1"`,
+		`"lang": "zh"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestDriveSecureLabelList_ValidatePageSize(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	err := mountAndRunDrive(t, DriveSecureLabelList, []string{
+		"+secure-label-list",
+		"--page-size", "11",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil || !strings.Contains(err.Error(), "page-size") {
+		t.Fatalf("expected page-size validation error, got: %v", err)
+	}
+}
+
+func TestDriveSecureLabelList_ExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/my_secure_labels?page_size=10",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{"id": "7217780879644737540", "name": "L1"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveSecureLabelList, []string{
+		"+secure-label-list",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"L1"`) {
+		t.Fatalf("stdout missing label:\n%s", stdout.String())
+	}
+}
+
+func TestDriveSecureLabelUpdate_DryRunInfersTypeFromURL(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", "https://example.feishu.cn/docx/doxTok123?from=share",
+		"--label-id", "7217780879644737539",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{
+		"/open-apis/drive/v2/files/doxTok123/secure_label",
+		`"PATCH"`,
+		`"docx"`,
+		`"id": "7217780879644737539"`,
+		`"file_token": "doxTok123"`,
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("dry-run output missing %q:\n%s", want, out)
+		}
+	}
+}
+
+func TestDriveSecureLabelUpdate_ExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	stub := &httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/drive/v2/files/doxTok123/secure_label?type=docx",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", "doxTok123",
+		"--type", "docx",
+		"--label-id", "7217780879644737539",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("parse body: %v", err)
+	}
+	if body["id"] != "7217780879644737539" {
+		t.Fatalf("id = %v, want label id", body["id"])
+	}
+}
+
+func TestDriveSecureLabelUpdate_DowngradeApprovalReturnsAPIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/drive/v2/files/doxTok123/secure_label",
+		Status: 403,
+		Body: map[string]interface{}{
+			"code": 1063013, "msg": "Security label downgrade requires approval",
+		},
+	})
+
+	targetURL := "https://example.feishu.cn/docx/doxTok123"
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", targetURL,
+		"--label-id", "7217780879644737539",
+		"--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected 1063013 error")
+	}
+	if !strings.Contains(err.Error(), "Security label downgrade requires approval") {
+		t.Fatalf("expected raw API error message, got: %v", err)
+	}
+}
--- a/shortcuts/drive/shortcuts.go
+++ b/shortcuts/drive/shortcuts.go
@@ -28,6 +28,8 @@ func Shortcuts() []common.Shortcut {
 		DriveSync,
 		DriveTaskResult,
 		DriveApplyPermission,
+		DriveSecureLabelList,
+		DriveSecureLabelUpdate,
 		DriveSearch,
 		DriveInspect,
 	}
--- a/shortcuts/drive/shortcuts_test.go
+++ b/shortcuts/drive/shortcuts_test.go
@@ -31,6 +31,8 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+sync",
 		"+task_result",
 		"+apply-permission",
+		"+secure-label-list",
+		"+secure-label-update",
 		"+search",
 		"+inspect",
 	}
--- a/shortcuts/sheets/lark_sheets_filter_views.go
+++ b/shortcuts/sheets/lark_sheets_filter_views.go
@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"strings"
+	"unicode/utf8"

 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -264,7 +265,7 @@ var SheetCreateFilterViewCondition = common.Shortcut{
 		{Name: "sheet-id", Desc: "sheet ID", Required: true},
 		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
 		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
-		{Name: "filter-type", Desc: "filter type: hiddenValue, number, text, color", Required: true},
+		{Name: "filter-type", Desc: "filter type: multiValue, number, text, color", Required: true},
 		{Name: "compare-type", Desc: "comparison operator (e.g. less, beginsWith, between)"},
 		{Name: "expected", Desc: "filter values JSON array (e.g. [\"6\"])", Required: true},
 	},
@@ -272,7 +273,7 @@ var SheetCreateFilterViewCondition = common.Shortcut{
 		if _, err := validateFilterViewToken(runtime); err != nil {
 			return err
 		}
-		return validateExpectedFlag(runtime.Str("expected"))
+		return validateFilterViewConditionFlags(runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		token, _ := validateFilterViewToken(runtime)
@@ -306,7 +307,7 @@ var SheetUpdateFilterViewCondition = common.Shortcut{
 		{Name: "sheet-id", Desc: "sheet ID", Required: true},
 		{Name: "filter-view-id", Desc: "filter view ID", Required: true},
 		{Name: "condition-id", Desc: "column letter (e.g. E)", Required: true},
-		{Name: "filter-type", Desc: "filter type: hiddenValue, number, text, color"},
+		{Name: "filter-type", Desc: "filter type: multiValue, number, text, color"},
 		{Name: "compare-type", Desc: "comparison operator"},
 		{Name: "expected", Desc: "filter values JSON array"},
 	},
@@ -319,10 +320,7 @@ var SheetUpdateFilterViewCondition = common.Shortcut{
 			!hasNonEmptyStringFlag(runtime, "expected") {
 			return common.FlagErrorf("specify at least one of --filter-type, --compare-type, or --expected")
 		}
-		if s := runtime.Str("expected"); s != "" {
-			return validateExpectedFlag(s)
-		}
-		return nil
+		return validateFilterViewConditionFlags(runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		token, _ := validateFilterViewToken(runtime)
@@ -469,6 +467,55 @@ func validateExpectedFlag(s string) error {
 	return nil
 }

+func validateFilterViewConditionFlags(runtime *common.RuntimeContext) error {
+	filterType := strings.TrimSpace(runtime.Str("filter-type"))
+	if filterType != "" {
+		switch filterType {
+		case "multiValue", "number", "text", "color":
+		case "hiddenValue":
+			return output.ErrValidation("--filter-type hiddenValue is no longer supported by Lark Sheets filter view conditions; use --filter-type multiValue with --expected values to show, and omit --compare-type")
+		default:
+			return output.ErrValidation("--filter-type must be one of multiValue, number, text, color; got %q", filterType)
+		}
+	}
+
+	expected := runtime.Str("expected")
+	if filterType == "multiValue" {
+		if strings.TrimSpace(runtime.Str("compare-type")) != "" {
+			return output.ErrValidation("--compare-type must be omitted when --filter-type multiValue")
+		}
+		values, err := parseExpectedStringArray(expected)
+		if err != nil {
+			return err
+		}
+		if len(values) == 0 {
+			return output.ErrValidation("--expected must contain at least one value when --filter-type multiValue")
+		}
+		for i, value := range values {
+			if utf8.RuneCountInString(value) > 50000 {
+				return output.ErrValidation("--expected[%d] must be 50000 characters or fewer when --filter-type multiValue", i)
+			}
+		}
+		return nil
+	}
+
+	if expected != "" {
+		return validateExpectedFlag(expected)
+	}
+	return nil
+}
+
+func parseExpectedStringArray(s string) ([]string, error) {
+	if strings.TrimSpace(s) == "" {
+		return nil, output.ErrValidation("--expected is required when --filter-type multiValue")
+	}
+	var values []string
+	if err := json.Unmarshal([]byte(s), &values); err != nil {
+		return nil, output.ErrValidation("--expected must be a JSON string array when --filter-type multiValue (e.g. [\"A\",\"B\"]), got: %s", s)
+	}
+	return values, nil
+}
+
 func buildConditionBody(runtime *common.RuntimeContext, includeConditionID bool) map[string]interface{} {
 	body := map[string]interface{}{}
 	if includeConditionID {
--- a/shortcuts/sheets/lark_sheets_sheet_filter_view_test.go
+++ b/shortcuts/sheets/lark_sheets_sheet_filter_view_test.go
@@ -334,6 +334,104 @@ func TestCreateFilterViewConditionExecuteSuccess(t *testing.T) {
 	}
 }

+func TestCreateFilterViewConditionMultiValueExecuteSuccess(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "POST", URL: "/open-apis/sheets/v3/spreadsheets/shtTOKEN/sheets/sheet1/filter_views/fv1/conditions",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{
+			"condition": map[string]interface{}{"condition_id": "C", "filter_type": "multiValue"},
+		}},
+	}
+	reg.Register(stub)
+	err := mountAndRunSheets(t, SheetCreateFilterViewCondition, []string{
+		"+create-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+		"--condition-id", "C", "--filter-type", "multiValue",
+		"--expected", `["A","B"]`, "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("parse body: %v", err)
+	}
+	if body["filter_type"] != "multiValue" {
+		t.Fatalf("unexpected filter_type: %v", body["filter_type"])
+	}
+	if _, ok := body["compare_type"]; ok {
+		t.Fatalf("multiValue body must omit compare_type: %v", body)
+	}
+	expected, ok := body["expected"].([]interface{})
+	if !ok || len(expected) != 2 || expected[0] != "A" || expected[1] != "B" {
+		t.Fatalf("unexpected expected values: %#v", body["expected"])
+	}
+}
+
+func TestCreateFilterViewConditionRejectsHiddenValue(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetCreateFilterViewCondition, []string{
+		"+create-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+		"--condition-id", "C", "--filter-type", "hiddenValue",
+		"--expected", `["A"]`, "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected hiddenValue validation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "--filter-type hiddenValue is no longer supported") {
+		t.Fatalf("unexpected error message: %v", err)
+	}
+}
+
+func TestCreateFilterViewConditionRejectsInvalidMultiValueFlags(t *testing.T) {
+	cases := []struct {
+		name     string
+		args     []string
+		wantText string
+	}{
+		{
+			name:     "compare type",
+			args:     []string{"--compare-type", "less", "--expected", `["A"]`},
+			wantText: "--compare-type must be omitted",
+		},
+		{
+			name:     "empty expected",
+			args:     []string{"--expected", `[]`},
+			wantText: "at least one value",
+		},
+		{
+			name:     "non-string expected",
+			args:     []string{"--expected", `[1]`},
+			wantText: "JSON string array",
+		},
+		{
+			name:     "too long expected",
+			args:     []string{"--expected", `["` + strings.Repeat("x", 50001) + `"]`},
+			wantText: "50000 characters",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+			args := []string{
+				"+create-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+				"--sheet-id", "sheet1", "--filter-view-id", "fv1",
+				"--condition-id", "C", "--filter-type", "multiValue",
+			}
+			args = append(args, tc.args...)
+			args = append(args, "--as", "user")
+			err := mountAndRunSheets(t, SheetCreateFilterViewCondition, args, f, stdout)
+			if err == nil {
+				t.Fatalf("expected validation error for %s, got nil", tc.name)
+			}
+			if !strings.Contains(err.Error(), tc.wantText) {
+				t.Fatalf("unexpected error message: %v", err)
+			}
+		})
+	}
+}
+
 // ── UpdateFilterViewCondition ────────────────────────────────────────────────

 func TestUpdateFilterViewConditionDryRun(t *testing.T) {
@@ -384,6 +482,21 @@ func TestUpdateFilterViewConditionRejectsNoFields(t *testing.T) {
 	}
 }

+func TestUpdateFilterViewConditionRejectsHiddenValue(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetUpdateFilterViewCondition, []string{
+		"+update-filter-view-condition", "--spreadsheet-token", "shtTOKEN",
+		"--sheet-id", "sheet1", "--filter-view-id", "fv1", "--condition-id", "C",
+		"--filter-type", "hiddenValue", "--expected", `["A"]`, "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected hiddenValue validation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "--filter-type hiddenValue is no longer supported") {
+		t.Fatalf("unexpected error message: %v", err)
+	}
+}
+
 // ── ListFilterViewConditions ─────────────────────────────────────────────────

 func TestListFilterViewConditionsDryRun(t *testing.T) {
--- a/skills/lark-doc/SKILL.md
+++ b/skills/lark-doc/SKILL.md
@@ -32,6 +32,11 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。

 ## 快速决策
+- 用户需要“某个 block 的直达链接 / 锚点链接”时：返回 `文档基础 URL#block_id`。如果当前只有文档 URL 没有 block_id，先用 `docs +fetch --detail with-ids` 拿到目标 block 的 id
+- 例：
+  - 已知文档 URL = `https://xxx.feishu.cn/docx/doxcn123`
+  - 已知 block_id = `blkcn456`
+  - 应返回 `https://xxx.feishu.cn/docx/doxcn123#blkcn456`
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载
 - 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
--- a/skills/lark-doc/references/lark-doc-create.md
+++ b/skills/lark-doc/references/lark-doc-create.md
@@ -86,4 +86,3 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
 - [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
 - [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数
-
--- a/skills/lark-doc/references/lark-doc-fetch.md
+++ b/skills/lark-doc/references/lark-doc-fetch.md
@@ -36,10 +36,9 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
 | 意图 | `--detail` | 说明 |
 |------|-----------|------|
 | **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |
-| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于 `+update` 的 `--block-id` |
+| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于 `+update` 的 `--block-id`，也可用于拼接 `文档URL#block_id` 形式的直达链接 |
 | **编辑**：任何修改文档内容的需求 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |

-
 ## 选 `--scope`（读取范围）

 `--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**
--- a/skills/lark-doc/references/lark-doc-whiteboard.md
+++ b/skills/lark-doc/references/lark-doc-whiteboard.md
@@ -4,56 +4,133 @@

 ## 两个 Skill 的职责边界

-| Skill | 核心职责 | 约束 |
-|------|------|------|
-| `lark-doc` | 识别画板机会、判断简单/复杂、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；简单图不需要读取 `lark-whiteboard` |
-| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅复杂图或已有画板更新时由独立 SubAgent 读取 |
+| Skill             | 核心职责                                                      | 约束                              |
+|-------------------|-----------------------------------------------------------|---------------------------------|
+| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
+| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |

 ## 画板优先规则

 写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。

-同一篇文档可以有多个画板。优先多个聚焦画板，而不是把所有信息塞进一张大图。
+同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。

 ## 文档与画板协同流程

 ### 步骤 1：识别画板机会

-| 场景 | 入口 |
-|------|------|
-| 文档中需要插入简单新画板 | 走步骤 2A |
-| 文档中需要插入复杂新画板 | 走步骤 2B |
-| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |
-| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
+| 场景                      | 入口                                                        |
+|-------------------------|-----------------------------------------------------------|
+| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表                                     |
+| 文档中需要插入其他图表/自定义图形       | 步骤 2B: 使用 SVG 插入图表                                        |
+| 已有画板需要更新内容              | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |
+| 只查看 / 下载已有画板            | 切换至 `lark-whiteboard`，不走本流程                               |

-简单图判定：节点少、静态、布局可控、适合一个完整自包含 SVG 表达，例如小型流程、2-3 方对比、小型状态机、简单时间线或小型示意图。
+> [!IMPORTANT]
+> ⚠️ **分别对每个图表进行决策**

-复杂图判定：节点多、跨泳道/跨系统、需要自动布局或精细排版、包含数据图表、组织架构、复杂架构、复杂依赖、已有画板更新，或需要 `lark-whiteboard` 的渲染验证。
+如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
+中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
+SubAgent 插入 SVG。

-### 步骤 2A：简单图 — SubAgent 直接插入 SVG 画板
+建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表
+
+### 步骤 2A: 使用 mermaid 插入图表
+
+```xml
+
+<whiteboard type="mermaid">
+    mermaid 代码...
+</whiteboard>
+```
+
+### 步骤 2B: SubAgent 使用 SVG 插入图表

 主 Agent 启动 SubAgent，让它用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入：

 ```xml
-<whiteboard type="svg"><svg ...>...</svg></whiteboard>
+
+<whiteboard type="svg">
+    <svg...>...
+    </svg>
+</whiteboard>
 ```

-简单图 SubAgent 的最小上下文：
+Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
+
 - doc token、插入位置（标题 / block_id / command）
 - 图表目标、受众、源段落或数据
 - 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
 - SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源

-### 步骤 2B：复杂图 — 先创建空白画板
+#### 画板 SVG 设计指南

- 主 Agent 使用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入 `<whiteboard type="blank"></whiteboard>`。
- 从 v2 响应的 `data.document.new_blocks[]` 中读取 `block_type == "whiteboard"` 的 `block_token` 作为 board_token。
+使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
+**核心心智纠正 (重要)**：

-### 步骤 3B：复杂图或已有画板 — 启动 lark-whiteboard SubAgent
+- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, *
+  *这将被视为不及格！**
+- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀,
+  大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
+
+##### SVG 设计 Workflow
+
+###### 1. 想清楚要画什么
+
+- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
+- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
+- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
+
+###### 2. 写 SVG
+
+> [!IMPORTANT]
+> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
+> 操作边界约束：
+
+- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
+- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
+- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
+- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
+
+###### 画板怎么处理 SVG
+
+画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但
+`<radialGradient>` / `<filter>` / `<clipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）
+**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
+
+**可识别的元素**
+
+- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
+- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
+- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
+- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
+- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
+
+> [!IMPORTANT]
+> ⚠️ ** 不支持的装饰特性**
+
+- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题
+  **
+
+###### 3.插入后审查
+
+插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png
+图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [
+`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as image \
+  --output ./preview.png
+```
+
+### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent

 复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。

 复杂图 SubAgent 的最小上下文：
+
 - board_token
 - 图表目标、推荐画板类型、受众
 - 与图表直接相关的源段落或数据
@@ -63,35 +140,12 @@

 ### 步骤 4：完成校验

- 简单 SVG：确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
- 复杂画板：确认每个 token 对应的画板都已填充真实内容
+- Mermaid: 确认插入的是 `<whiteboard type="mermaid">`，且内容 mermaid 语法完整
+- SVG: 确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
 - 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成

 ---

-## 语义与画板类型映射
-
-下表用于帮助主 Agent 判断简单/复杂路径，并给 SubAgent 指定推荐画板类型。
-
-| 语义 | 画板类型 |
-|------|------|
-| 小型流程/状态机/简单时间线/小型对比/小型示意图 | SVG 画板（简单路径） |
-| 架构/分层/技术方案/模块依赖/调用关系 | 架构图（复杂路径） |
-| 流程/审批/部署/业务流转/状态机 | 流程图（按复杂度分流） |
-| 跨角色流程/跨系统交互/端到端链路 | 泳道图（复杂路径） |
-| 组织/层级/汇报关系 | 组织架构图 |
-| 时间线/里程碑/版本规划 | 里程碑图 |
-| 因果/复盘/根因分析 | 鱼骨图 |
-| 方案对比/技术选型/功能矩阵 | 对比图 |
-| 循环/飞轮/闭环/增长链路 | 飞轮图 |
-| 层级占比/能力模型/需求层次 | 金字塔图 |
-| 矩形树图/层级面积占比 | 树状图 |
-| 转化漏斗/销售漏斗 | 漏斗图 |
-| 分类梳理/知识体系/思维导图/时序图/类图 | Mermaid |
-| 数据分布/占比/饼图 | Mermaid |
-| 简单自定义图形/小型 SVG 示意图 | SVG 画板（简单路径） |
-| 柱状图/条形图/数据对比 | 柱状图 |
-| 折线图/趋势图/时序数据 | 折线图 |

 ---

--- a/skills/lark-doc/references/style/lark-doc-create-workflow.md
+++ b/skills/lark-doc/references/style/lark-doc-create-workflow.md
@@ -35,12 +35,12 @@

 5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
 6. 评估样式达标（富 block 密度、元素多样性、连续 `<p>` 数量）
-7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、简单/复杂路径和用于画图的源内容
+7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容

 ### 第四波 — 画板与润色（并行 Agent）
+
 8. **优先处理第三波识别出的画板需求**：
-   - 简单图：启动 SVG SubAgent，直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；不读取 **lark-whiteboard**
-   - 复杂图：主 Agent 先插入 `<whiteboard type="blank"></whiteboard>` 并提取 `block_token`，再为每个 `block_token` 启动 SubAgent 使用 **lark-whiteboard** skill 写入画板
+   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
 9. Spawn 内容改写 Agent 定向润色：
   - 文字密集章节转为 `<table>`/`<grid>`/`<callout>`
   - 主要章节间补充 `<hr/>`
@@ -51,6 +51,8 @@

 内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。

-SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。

-复杂画板 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
--- a/skills/lark-doc/references/style/lark-doc-style.md
+++ b/skills/lark-doc/references/style/lark-doc-style.md
@@ -12,21 +12,20 @@

 ## 二、元素选择指南

-涉及图表需求时，先判定简单/复杂：简单图启动 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读取 **lark-whiteboard**；复杂图才使用空白画板 + **lark-whiteboard** SubAgent。
+涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
+
+| 场景                                         | 推荐方案                                  |
+|--------------------------------------------|---------------------------------------|
+| 核心结论 / 摘要 / 注意事项                           | `<callout>` + emoji + 背景色             |
+| 重要方案对比 / 优劣势 / Before vs After             | `<grid>` 2 列分栏；SVG SubAgent           |
+| 简短低风险对比                                    | `<grid>` 2 列分栏                        |
+| 3+ 属性的结构化数据 / 指标表                          | `<table>` + 表头背景色                     |
+| 任务清单 / 检查项                                 | `<checkbox>`                          |
+| 代码片段                                       | `<pre lang="x" caption="说明">`         |
+| 引用 / 公式                                    | `<blockquote>` / `<latex>`            |
+| 操作入口 / 跳转链接                                | `<button>` / `<a type="url-preview">` |
+| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 /思维导图等 | 画板图表                                  |

-| 场景 | 推荐方案                                                          |
-|-|---------------------------------------------------------------|
-| 核心结论 / 摘要 / 注意事项 | `<callout>` + emoji + 背景色                                     |
-| 重要方案对比 / 优劣势 / Before vs After | `<grid>` 2 列分栏；简单 SVG SubAgent；复杂矩阵用 lark-whiteboard SubAgent |
-| 简短低风险对比 | `<grid>` 2 列分栏                                                |
-| 3+ 属性的结构化数据 / 指标表 | `<table>` + 表头背景色                                             |
-| 任务清单 / 检查项 | `<checkbox>`                                                  |
-| 代码片段 | `<pre lang="x" caption="说明">`                                 |
-| 引用 / 公式 | `<blockquote>` / `<latex>`                                    |
-| 操作入口 / 跳转链接 | `<button>` / `<a type="url-preview">`                         |
-| 简单流程图 / 小型状态机 / 小型时间线 | 简单 SVG SubAgent                                               |
-| 简单自定义图形 / 小型 SVG 示意图 | 简单 SVG SubAgent                                               |
-| 复杂架构图 / 数据图 / 思维导图 / 组织架构 | 空白画板 + lark-whiteboard SubAgent                               |

 ### 画板意图识别

@@ -49,28 +48,8 @@

 **判断规则：**
 - 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
- 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读取 **lark-whiteboard**
- 复杂图或已有画板更新才先插入 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 使用 **lark-whiteboard** skill 写入内容
 - 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
-
-### 画板语法与插入
-
-> **提醒：** `docs +update` 不能编辑已有画板内容；下面的语法都是**新增**画板块。修改已有画板需启动 SubAgent 读取 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md)。
-
-#### 简单 SVG 画板（SubAgent 插入）
-
-1. 主 Agent 启动 SubAgent，传入 doc token、插入位置、图表目标和源内容
-2. SubAgent 使用 `<whiteboard type="svg">完整自包含 SVG</whiteboard>` 通过 `docs +create --api-version v2` / `docs +update --api-version v2` 插入
-3. SVG 必须包含 `<svg>` 根节点和 `viewBox`，不要引用外部图片、脚本或远程资源
-
-#### 复杂画板（空白画板 + lark-whiteboard SubAgent）
-
-1. 用 `<whiteboard type="blank"></whiteboard>` 通过 `docs +create --api-version v2` / `docs +update --api-version v2` 插入空白画板
-2. 从 v2 响应 `data.document.new_blocks` 中提取画板 `block_token`
-3. 必须启动 SubAgent，把 `block_token`、图表目标、推荐画板类型和源内容交给它
-4. SubAgent 读取 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md) skill 并写入该画板；主 Agent 不直接调用画板渲染流程
-
-更完整的协同流程见 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
+- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。

 ## 三、颜色语义

--- a/skills/lark-doc/references/style/lark-doc-update-workflow.md
+++ b/skills/lark-doc/references/style/lark-doc-update-workflow.md
@@ -25,14 +25,13 @@
   - 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids`
   - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope"
 2. 系统性评估：结构清晰度、富 block 密度（≥40%）、元素多样性（≥3种）、连续 `<p>` 是否超过 3 段、是否有开头 callout 和章节 `<hr/>`
-3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、简单/复杂路径和源内容片段
+3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
 4. 向用户简要说明改进计划（包含识别出的画板机会）

 ### 第二波 — 定向改写（并行 Agent）

 5. **优先处理第一波识别出的画板候选段落**：
-   - 简单图：启动 SVG SubAgent，直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；不读取 **lark-whiteboard**
-   - 复杂图：主 Agent 先插入 `<whiteboard type="blank"></whiteboard>` 并提取 `block_token`，再为每个 `block_token` 启动 SubAgent 使用 **lark-whiteboard** skill 写入画板
+   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
 6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：（见 `lark-doc-style.md`）
   - 开头适当添加 `<callout>`、重组引言
   - 纯文本转为 `<grid>`/`<table>`/`<callout>`
@@ -47,8 +46,10 @@

 内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。

-SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。

-复杂画板 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。

 **上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。
--- a/skills/lark-drive/SKILL.md
+++ b/skills/lark-drive/SKILL.md
@@ -283,6 +283,8 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [`+secure-label-list`](references/lark-drive-secure-label.md) | List secure labels available to the current user |
+| [`+secure-label-update`](references/lark-drive-secure-label.md) | Update a Drive file/document secure label; downgrade approval errors require opening the document UI |

 ## API Resources

--- a/skills/lark-drive/references/lark-drive-secure-label.md
+++ b/skills/lark-drive/references/lark-drive-secure-label.md
@@ -0,0 +1,52 @@
+# drive +secure-label-list / +secure-label-update（云文档密级标签）
+
+## 何时使用
+
+- `drive +secure-label-list`：查询当前用户可用的密级标签，先拿到目标 `id`。
+- `drive +secure-label-update`：把目标云文档调整为指定密级标签。
+
+这两个 shortcut 都使用用户身份（`--as user`）。修改密级前，通常先执行 `+secure-label-list` 确认可用标签 ID。
+
+## 查询可用密级标签
+
+```bash
+lark-cli drive +secure-label-list --page-size 10 --lang zh
+```
+
+可选参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--page-size` | 分页大小，范围 `1..10`，默认 `10` |
+| `--page-token` | 上一页响应里的 `page_token` |
+| `--lang` | 标签语言：`zh`、`en`、`ja` |
+
+底层接口：`GET /open-apis/drive/v2/my_secure_labels`。
+
+## 修改文档密级
+
+```bash
+lark-cli drive +secure-label-update \
+  --token "https://example.feishu.cn/docx/doxcnxxxx" \
+  --label-id "7217780879644737539"
+```
+
+参数：
+
+| 参数 | 说明 |
+|------|------|
+| `--token` | 目标文档 URL 或 bare token；URL 可自动推断 `--type` |
+| `--type` | bare token 必填；URL 输入时可省略。可选：`doc`、`docx`、`sheet`、`file`、`bitable`、`mindnote`、`slides` |
+| `--label-id` | 要设置的密级标签 ID |
+
+底层接口：`PATCH /open-apis/drive/v2/files/:file_token/secure_label`，query 参数 `type`，请求体 `{ "id": "<label-id>" }`。
+
+## 错误处理
+
+CLI 不会在 shortcut 中为密级错误码追加专用 hint；agent 必须根据返回的 `error.code` 做以下引导。
+
+| 错误码 | 含义 | 引导 |
+|--------|------|------|
+| `1063013` | 密级降级需要审批 | 提示用户打开目标文档，在文档界面完成密级降级审批后重试；如果用户传入的是文档 URL，必须把该 URL 一并给用户作为操作入口 |
+
+遇到 `1063013` 时，不要继续重试 API，也不要提示补 scope；这是文档侧审批流程要求，需要用户到文档里操作。
--- a/skills/lark-event/SKILL.md
+++ b/skills/lark-event/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: lark-event
 version: 1.0.0
-description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM message receive, reactions, chat member changes, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
+description: "Lark/Feishu real-time event listening / subscribing / consuming: stream events as NDJSON via `lark-cli event consume <EventKey>` (covers IM messages/reactions/chat changes, VC meeting ended, Minutes generated, etc.). Use for Lark bots, real-time message processing, long-running subscribers, streaming webhook/push handlers. Supports `--max-events` / `--timeout` bounded runs and a stderr ready-marker contract — designed for AI agents running as subprocesses."
 metadata:
  requires:
    bins: ["lark-cli"]
@@ -143,3 +143,5 @@ Lark-defined semantic tags (**not** JSON Schema's standard `format`). Common val
 | Topic | Reference | Coverage |
 |---|---|---|
 | IM | [`references/lark-event-im.md`](references/lark-event-im.md) | Catalog of 11 IM EventKeys + shape notes (flat vs V2 envelope) + `im.message.receive_v1` field gotchas (`sender_id` is open_id only; `.content` is plain text except for `interactive` cards) + common jq recipes (filter by chat_type / message_type / sender) |
+| VC | [`references/lark-event-vc.md`](references/lark-event-vc.md) | Catalog of 1 VC EventKey (`vc.meeting.participant_meeting_ended_v1`) + field reference + time conversion gotchas (unix seconds → local RFC3339) |
+| Minutes | [`references/lark-event-minutes.md`](references/lark-event-minutes.md) | Catalog of 1 Minutes EventKey (`minutes.minute.generated_v1`) + field reference + enrichment & degradation semantics (minute detail API fills `title`; `minute_source` from event payload survives enrichment failure) |
--- a/skills/lark-event/references/lark-event-minutes.md
+++ b/skills/lark-event/references/lark-event-minutes.md
@@ -0,0 +1,54 @@
+# Minutes Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (1)
+
+| EventKey | Purpose |
+|---|---|
+| `minutes.minute.generated_v1` | A minute (妙记) has been generated |
+
+This key uses a **Custom schema** (flat output at `.xxx`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `minutes.minute.generated_v1` | `minutes:minutes.basic:read` | user |
+
+Requires `--as user`.
+
+## `minutes.minute.generated_v1`
+
+### Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type; always `minutes.minute.generated_v1` |
+| `event_id` | string | Globally unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
+| `minute_token` | string | Minute token |
+| `title` | string | Minute title (enriched via detail API) |
+| `minute_source` | object | Minute source metadata; only present when the source is a meeting |
+| `minute_source.source_type` | string | Source type; only present when the source is a meeting (value: `meeting`) |
+| `minute_source.source_entity_id` | string | Source entity ID (meeting ID); only present when the source is a meeting |
+
+### Enrichment & degradation
+
+The Process hook calls `GET /open-apis/minutes/v1/minutes/{minute_token}` to enrich `title`. If the detail API fails, this field is left empty — the base fields (`type`, `event_id`, `timestamp`, `minute_token`, `minute_source`) are always present.
+
+`minute_source` is populated from the event payload directly (not the detail API), so it survives enrichment failures. Note: `minute_source` is only present when the minute originates from a meeting; for other sources (e.g. recording, local upload) this field is absent.
+
+### Example
+
+```bash
+lark-cli event consume minutes.minute.generated_v1 --as user
+
+# Project title and token only (skip events where enrichment failed)
+lark-cli event consume minutes.minute.generated_v1 --as user \
+  --jq 'select(.title != "") | {minute_token, title}'
+
+# Filter by source type
+lark-cli event consume minutes.minute.generated_v1 --as user \
+  --jq 'select(.minute_source.source_type == "meeting") | {minute_token, title}'
+```
--- a/skills/lark-event/references/lark-event-vc.md
+++ b/skills/lark-event/references/lark-event-vc.md
@@ -0,0 +1,50 @@
+# VC Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (1)
+
+| EventKey | Purpose |
+|---|---|
+| `vc.meeting.participant_meeting_ended_v1` | A meeting the current user participates in has ended |
+
+This key uses a **Custom schema** (flat output at `.xxx`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `vc.meeting.participant_meeting_ended_v1` | `vc:meeting.meetingevent:read` | user |
+
+Requires `--as user`.
+
+## `vc.meeting.participant_meeting_ended_v1`
+
+### Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type; always `vc.meeting.participant_meeting_ended_v1` |
+| `event_id` | string | Globally unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
+| `meeting_id` | string | Meeting ID |
+| `topic` | string | Meeting topic |
+| `meeting_no` | string | Meeting number |
+| `start_time` | string | Meeting start time in RFC3339, converted to the local timezone |
+| `end_time` | string | Meeting end time in RFC3339, converted to the local timezone |
+| `calendar_event_id` | string | Calendar event ID associated with the meeting |
+
+### Gotchas
+
+- `start_time` / `end_time` are **not** the raw unix-seconds from OAPI — the Process hook converts them to local-timezone RFC3339. If the raw value is empty or non-numeric, the field is left empty.
+- No detail API call is made; all fields come from the event payload itself.
+
+### Example
+
+```bash
+lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user
+
+# Project meeting topic and end time only
+lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user \
+  --jq '{meeting: .meeting_id, topic: .topic, ended: .end_time}'
+```
--- a/skills/lark-sheets/references/lark-sheets-filter-views.md
+++ b/skills/lark-sheets/references/lark-sheets-filter-views.md
@@ -123,6 +123,11 @@ lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx"
 lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
  --sheet-id "<sheetId>" --filter-view-id "<fvId>" \
  --condition-id "G" --filter-type "text" --compare-type "beginsWith" --expected '["a"]'
+
+# 多值筛选：只展示 Grade 为 A 或 B 的行（multiValue 不传 compare-type）
+lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx" \
+  --sheet-id "<sheetId>" --filter-view-id "<fvId>" \
+  --condition-id "C" --filter-type "multiValue" --expected '["A","B"]'
 ```

 参数：
@@ -134,7 +139,7 @@ lark-cli sheets +create-filter-view-condition --spreadsheet-token "shtxxxxxxxx"
 | `--sheet-id` | 是 | 工作表 ID |
 | `--filter-view-id` | 是 | 筛选视图 ID |
 | `--condition-id` | 是 | 列字母，如 `E` |
-| `--filter-type` | 是 | `hiddenValue` / `number` / `text` / `color` |
+| `--filter-type` | 是 | `multiValue` / `number` / `text` / `color` |
 | `--compare-type` | 否 | 比较运算符 |
 | `--expected` | 是 | 筛选值 JSON 数组 |

--- a/tests/cli_e2e/drive/coverage.md
+++ b/tests/cli_e2e/drive/coverage.md
@@ -1,9 +1,9 @@
 # Drive CLI E2E Coverage

 ## Metrics
- Denominator: 29 leaf commands
- Covered: 9
- Coverage: 31.0%
+- Denominator: 31 leaf commands
+- Covered: 10
+- Coverage: 32.3%

 ## Summary
 - TestDrive_FilesCreateFolderWorkflow: proves `drive files create_folder` in `create_folder as bot`; helper asserts the returned folder token and registers best-effort cleanup via `drive files delete`.
@@ -13,6 +13,7 @@
 - TestDrive_ApplyPermissionDryRun / TestDrive_ApplyPermissionDryRunRejectsFullAccess: dry-run coverage for `drive +apply-permission`; asserts URL→type inference for docx/sheet/slides, explicit `--type` overriding URL inference when both a recognized URL and `--type` are supplied, bare-token + explicit `--type` path, request method/URL/type-query/perm/remark body shape, optional `remark` omission when unset, and client-side rejection of `--perm full_access`. Runs without hitting the live API.
 - TestDriveAddCommentDryRun_File: dry-run coverage for `drive +add-comment` on supported Drive file targets; pins the `metas.batch_query -> files/:token/new_comments` request chain, `file_type=file`, and the required placeholder `anchor.block_id`.
 - TestDriveAddCommentMarkdownFileWorkflow: opt-in live workflow skeleton for the same path, gated by `LARK_DRIVE_MD_COMMENT_E2E=1`.
+- TestDrive_SecureLabelDryRun: dry-run coverage for `drive +secure-label-list` and `drive +secure-label-update`; asserts label-list query params and update URL→type inference, request method/URL/type query, and `label-id` body shape. Runs without hitting live APIs because update can trigger document-level security approval flows.
 - TestDriveExportDryRun_FileNameMetadata: dry-run coverage for `drive +export`; asserts export task request shape and local `--file-name` / `--output-dir` metadata without calling live APIs.
 - TestDrive_PullDryRun / TestDrive_PullDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +pull`; asserts the list-files request shape, Validate-stage safety guards, and acceptance of `--on-duplicate-remote=rename|newest|oldest` by the real CLI binary.
 - TestDrive_PushDryRun / TestDrive_PushDryRunAcceptsDuplicateRemoteStrategies: dry-run coverage for `drive +push`; asserts the list-files request shape, Validate-stage safety guards, conditional delete preflight, and acceptance of `--on-duplicate-remote=newest|oldest` by the real CLI binary.
@@ -34,6 +35,8 @@
 | ✕ | drive +move | shortcut |  | none | no move workflow yet |
 | ✓ | drive +pull | shortcut | drive_pull_dryrun_test.go::TestDrive_PullDryRun + drive_duplicate_sync_workflow_test.go::TestDrive_DuplicateRemoteWorkflow | `--local-dir`; `--folder-token`; `--on-duplicate-remote=rename\|newest\|oldest`; `--delete-local --yes` guard | dry-run locks flag/validate shape; live workflow proves duplicate fail-fast and rename recovery |
 | ✓ | drive +push | shortcut | drive_push_dryrun_test.go::TestDrive_PushDryRun + drive_duplicate_sync_workflow_test.go::TestDrive_DuplicateRemoteWorkflow | `--local-dir`; `--folder-token`; `--if-exists`; `--on-duplicate-remote=newest\|oldest`; `--delete-remote --yes` | dry-run locks flag/validate shape; live workflow proves overwrite + duplicate cleanup converges status |
+| ✓ | drive +secure-label-list | shortcut | drive_secure_label_dryrun_test.go::TestDrive_SecureLabelDryRun | `--page-size`; `--page-token`; `--lang` | dry-run only; live label availability depends on tenant security-label configuration |
+| ✓ | drive +secure-label-update | shortcut | drive_secure_label_dryrun_test.go::TestDrive_SecureLabelDryRun | `--token` URL inference; `--type`; `--label-id` body | dry-run only; live update can require document-level approval or mutate a fixture document's security level |
 | ✓ | drive +status | shortcut | drive_status_workflow_test.go::TestDrive_StatusWorkflow + drive_status_dryrun_test.go::TestDrive_StatusDryRun + drive_duplicate_sync_workflow_test.go::TestDrive_DuplicateRemoteWorkflow | `--local-dir`; `--folder-token`; bucketed `new_local` / `new_remote` / `modified` / `unchanged` outputs | dry-run pins request shape; live workflows cover both normal hashing buckets and duplicate-remote failure |
 | ✓ | drive +sync | shortcut | drive_sync_dryrun_test.go::TestDrive_SyncDryRun + drive_sync_workflow_test.go::TestDrive_SyncWorkflow + drive_sync_workflow_test.go::TestDrive_SyncEmptyDirWorkflow | `--local-dir`; `--folder-token`; `--on-conflict=remote-wins\|local-wins\|keep-both\|ask`; `--on-duplicate-remote=fail\|newest\|oldest`; `--quick` | dry-run validates request shape, flag acceptance, and path safety guards; live workflow proves new_remote→pull, new_local→push, remote-wins/local-wins/keep-both conflict resolution, empty directory creation, and post-sync convergence |
 | ✕ | drive +task_result | shortcut |  | none | no async task-result workflow yet |
--- a/tests/cli_e2e/drive/drive_secure_label_dryrun_test.go
+++ b/tests/cli_e2e/drive/drive_secure_label_dryrun_test.go
@@ -0,0 +1,98 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestDrive_SecureLabelDryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	tests := []struct {
+		name       string
+		args       []string
+		wantMethod string
+		wantURL    string
+		assert     func(t *testing.T, out string)
+	}{
+		{
+			name: "list available labels",
+			args: []string{
+				"drive", "+secure-label-list",
+				"--page-size", "5",
+				"--page-token", "page_1",
+				"--lang", "zh",
+				"--dry-run",
+			},
+			wantMethod: "GET",
+			wantURL:    "/open-apis/drive/v2/my_secure_labels",
+			assert: func(t *testing.T, out string) {
+				if got := gjson.Get(out, "api.0.params.page_size").Int(); got != 5 {
+					t.Fatalf("page_size = %d, want 5\nstdout:\n%s", got, out)
+				}
+				if got := gjson.Get(out, "api.0.params.page_token").String(); got != "page_1" {
+					t.Fatalf("page_token = %q, want page_1\nstdout:\n%s", got, out)
+				}
+				if got := gjson.Get(out, "api.0.params.lang").String(); got != "zh" {
+					t.Fatalf("lang = %q, want zh\nstdout:\n%s", got, out)
+				}
+			},
+		},
+		{
+			name: "update label with URL inference",
+			args: []string{
+				"drive", "+secure-label-update",
+				"--token", "https://example.feishu.cn/docx/doxcnE2E001?from=share",
+				"--label-id", "7217780879644737539",
+				"--dry-run",
+			},
+			wantMethod: "PATCH",
+			wantURL:    "/open-apis/drive/v2/files/doxcnE2E001/secure_label",
+			assert: func(t *testing.T, out string) {
+				if got := gjson.Get(out, "api.0.params.type").String(); got != "docx" {
+					t.Fatalf("type = %q, want docx\nstdout:\n%s", got, out)
+				}
+				if got := gjson.Get(out, "api.0.body.id").String(); got != "7217780879644737539" {
+					t.Fatalf("body.id = %q, want label id\nstdout:\n%s", got, out)
+				}
+				if got := gjson.Get(out, "file_token").String(); got != "doxcnE2E001" {
+					t.Fatalf("file_token = %q, want doxcnE2E001\nstdout:\n%s", got, out)
+				}
+			},
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+			t.Cleanup(cancel)
+
+			result, err := clie2e.RunCmd(ctx, clie2e.Request{
+				Args:      tt.args,
+				DefaultAs: "user",
+			})
+			require.NoError(t, err)
+			result.AssertExitCode(t, 0)
+			out := result.Stdout
+			if got := gjson.Get(out, "api.0.method").String(); got != tt.wantMethod {
+				t.Fatalf("method = %q, want %s\nstdout:\n%s", got, tt.wantMethod, out)
+			}
+			if got := gjson.Get(out, "api.0.url").String(); got != tt.wantURL {
+				t.Fatalf("url = %q, want %q\nstdout:\n%s", got, tt.wantURL, out)
+			}
+			tt.assert(t, out)
+		})
+	}
+}
Author	SHA1	Message	Date
/	823a55a1ef	fix: update sheets filter view condition validation	2026-05-27 17:31:19 +08:00
fangshuyu-768	e98471ce26	docs: document block anchor URLs in lark-doc skill (#1120 )	2026-05-27 14:32:46 +08:00
sang-neo03	9e2be14301	feat(schema): output json spec envelope for all API commands (#1048 ) * feat(schema): add envelope types and ordered properties container * feat(schema): build meta_data.json key-order index for property ordering * feat(schema): implement convertProperty with file/enum/range/nested handling * feat(schema): build inputSchema with x-in / file binary / yes injection * feat(schema): build outputSchema wrapping responseBody * feat(schema): build _meta with scopes/risk/access_tokens normalization * feat(schema): scaffold affordance overlay loader (PR-1 stub) * feat(schema): wire up AssembleEnvelope main entry point * feat(schema): parse dotted and space-separated path arguments * feat(schema): batch envelope assembly with optional method filter * feat(schema): implement L1-L3 envelope lint (structure/type/cross-field) * feat(schema): measure L4 coverage and gate all envelopes through L1-L3 * feat(schema): add golden test harness with UPDATE_GOLDEN refresh * test(schema): seed 20 golden envelopes covering edge cases * feat(schema): output MCP envelope as default JSON, preserve pretty mode Rewrites cmd/schema/schema.go so the default --format json branch emits MCP-spec envelopes via schema.AssembleAll/AssembleService/AssembleEnvelope. The legacy --format pretty branch is preserved verbatim and still uses printServices / printResourceList / printMethodDetail. Args max raised from 1 to 8 so the path can be supplied either as a single dotted argument (im.reactions.list) or as space-separated segments (im reactions list); both forms route through schema.ParsePath and produce byte-identical output. The completeSchemaPath function is extended to drive tab-completion for both forms: legacy dotted prefix when len(args) == 0, and per-segment resource/method completion when args already contains earlier segments. BREAKING CHANGE: default JSON output shape changes from the raw meta_data structure to an MCP envelope array/object. Existing scripts parsing the old shape must either pin --format pretty or migrate to the new envelope fields (name, description, inputSchema, outputSchema, _meta). * test(schema): cover envelope JSON output, space-form path, yes injection Replaces TestSchemaCmd_NoArgs with two variants reflecting the new default shape: TestSchemaCmd_NoArgs_Pretty asserts the legacy "Available services" text appears only under --format pretty, and TestSchemaCmd_NoArgs_JSON_IsArray asserts the default JSON output parses as an envelope array with at least 180 entries. Adds six new tests: - TestSchemaCmd_JSONIsEnvelope: single-method output has name / description / inputSchema / outputSchema / _meta keys and envelope_version "1.0". - TestSchemaCmd_SpaceSeparatedPath_EqualsDotted: dotted and space forms produce identical output bytes for the same command path. - TestSchemaCmd_ServiceListIsArray: schema <service> returns a JSON array whose every entry's name starts with "<service> ". - TestSchemaCmd_HighRiskYesInjection: high-risk-write commands inject inputSchema.properties.yes. - TestSchemaCmd_NoYesForReadRisk: read-risk commands do not inject yes. - TestSchemaCmd_PrettyUnchanged_KeyTextPresent: --format pretty still surfaces the legacy section markers (Parameters:, Response:, Identity:, Scopes:, CLI:). * feat(schema): assemble envelope from embedded data only for stability * chore(schema): lint cleanup * fix(schema): preserve dotted resource segments in envelope name Nested resources whose meta_data key contains a dot (e.g. chat.members, user_mailbox.templates) were previously split on '.' and rejoined with spaces, producing envelope names like 'im chat members bots'. AI consumers doing name.split(' ') and feeding the result back as argv got 'lark-cli im chat members bots' which the CLI rejects — the actual invocation form is 'lark-cli im chat.members bots'. Pass the dotted resource key as a single argv segment so the envelope name 'im chat.members bots' round-trips through name.split(' ') back to the CLI. Mirror the same convention in the golden harness so its single-method assembly matches the live AssembleService walk. * fix(schema): align MCP envelope output with JSON Schema 2020-12 contract - coerce enum literals to typed JSON values (integer to int64, number to float64, boolean to bool) so type:"integer" fields no longer emit string enums; sort numeric/boolean enums while preserving meta_data order for string enums that carry semantic priority - translate non-standard meta_data type:"list" to JSON Schema type:"array" with items:{} fallback when element shape is absent (covers the two mail attachment_ids fields) - render inputSchema.required even when empty so consumers see a stable envelope shape ("[]" means no required fields, not "field is missing") - reject trailing path segments in both JSON and pretty modes so schema im.messages.delete.foo errors instead of silently returning the delete method - drop dead "list type" entry from lint_test isKnownDataInconsistency whitelist now that list values are translated upstream * fix(schema): address CodeRabbit findings and stabilize CI tests CI fix - Replace hard-coded absolute key-order assertions in TestKeyOrderIndex_* and TestBuildInputSchema_* with set-membership and propagation invariants; the upstream meta_data API does not guarantee stable JSON key order across fetches, so the old tests were flaky on CI by design. - Skip byte-level TestGoldenEnvelopes when CI=true; golden snapshots are a manual refresh artefact tied to a specific meta_data fetch, not a CI gate. - Add TestMain to isolate registry-backed tests from any host ~/.lark-cli cache (LARKSUITE_CLI_CONFIG_DIR + LARKSUITE_CLI_REMOTE_META=off) so the suite gives the same answer on every machine. CodeRabbit review actionables - EmbeddedServiceNames returns a defensive copy so callers cannot mutate the package-level slice and affect subsequent assembly determinism. - coerceEnumValue is now also applied to default literals: integer fields no longer ship default: "500" — they ship default: 500 (same idea as the earlier enum coercion fix). - options-branch string enums preserve meta_data source order, matching the enum-branch policy; only numeric/boolean enums get sorted. - validatePropertyTypes now validates the array element schema itself (type, nested items), not only items.properties — previously a primitive element with an invalid type (e.g. items.type="list") slipped past lint. - OrderedProps.MarshalJSON falls back to alphabetical key order when Map has entries but Order is empty, instead of silently emitting {}. Tests pass locally and with CI=true env (simulating GitHub Actions). * chore(schema): refresh golden envelopes after meta_data drift Re-generated with UPDATE_GOLDEN=1 against the current meta_data.json snapshot. The bulk of the diff is upstream noise (description wording, enum entries, field order) which the CI snapshot diff can no longer reasonably gate (see previous commit). Side-effects of the code fixes in the parent commit are also captured: - integer-typed defaults now emit numeric literals (e.g. page_size default 500, not "500") thanks to coerceEnumValue - mail.user_mailbox.templates.create _meta.risk corrects to "write" (assembler already emitted "write"; the old golden was stale) * fix(schema): address CodeRabbit round-3 review findings - TestMain: cleanup now runs reliably. os.Exit skips deferred functions, so the previous defer os.RemoveAll(dir) never executed. Replace defer with explicit cleanup, and fail fast if MkdirTemp errors instead of silently running against the host cache (which defeats isolation). - convertProperty default coercion: when the literal cannot be coerced to the declared type (e.g. default:"" on integer field, used by meta_data to mean "no default"), omit the field entirely rather than emit a type-mismatched default. Removes a contract violation flagged on im.reactions.list.json#page_size. * feat(schema): wire affordance overlay into envelope _meta Replace the loadAffordance stub (which always returned nil and read from an empty embedded annotations/ directory) with parseAffordance, which lifts the affordance block from method["affordance"]. The block is authored under larksuite-cli-registry's registry-config.yaml in the overrides: section and flows through gen-registry.py's deep_merge into the embedded meta_data.json. Simplify buildMeta signature: the service/resourcePath/method args existed only to feed the old dotted-path lookup. Refresh 9 golden envelopes for unrelated upstream meta_data.json drift. * refactor(schema): drop x-in extension from inputSchema x-in (path/query/body) was an HTTP-shape leak in a CLI-facing tool spec. AI consumers call the CLI by name with named args — they never construct HTTP requests directly, so the path-vs-body-vs-query distinction is the CLI's internal concern, not part of the contract. Execution path (cmd/service/service.go) already reads location from meta_data.json directly, so removing x-in does not affect routing. Drop: - Property.XIn field - validXIn map and the two lint rules that depend on x-in (L1 "top-level missing x-in" and L2 "path field must be in required") - contains() helper, no longer referenced after the path-required rule went away Refresh 20 goldens for the now-absent x-in lines. * refactor(schema): wrap inputSchema into params/data/flags sub-objects Replace the flat inputSchema with a 3-bucket nested structure that mirrors the CLI's actual flag layout, so AI consumers can directly map envelope fields to lark-cli invocation: inputSchema: properties: params: { ...path + query fields } → CLI --params JSON data: { ...body fields } → CLI --data JSON flags: { yes: ... } → CLI --yes (only for high-risk-write) Each sub-object only appears when the method has the corresponding source, so read-only GETs have a single `params` block, body-only POSTs have a single `data` block, etc. The `flags` wrapper carries an explicit description marking it as a CLI control bucket (not API fields), so AI does not confuse `yes` with a backend parameter. Lint: - L2 walkForL2 helper recurses into params/data sub-objects so leaf invariants (format:binary on non-string, min<max, required-in-properties) still apply. - L3 yes-presence check now navigates flags.properties.yes. Refresh all 20 goldens for the new shape. * refactor(schema): drop flags wrapper, put yes at top level alongside params/data The flags wrapper added one extra layer for a single field. Flatten so inputSchema.properties has three siblings: inputSchema: properties: params: { ...path + query } → CLI --params data: { ...body } → CLI --data yes: { boolean, default:false } → CLI --yes (only when risk == high-risk-write) `yes` description strengthened to mark it as a CLI confirmation gate (consumed by lark-cli, not sent to the backend), so AI can still distinguish it from API fields without needing a wrapper. Lint L3 yes-presence check goes back to top-level Properties.Map["yes"]. Refresh 20 goldens. * feat(schema): add `file` top-level sub-object for binary upload fields Splits file fields out of `data` into their own sibling, so the four top-level slots in inputSchema map 1:1 to CLI flag dispatch: inputSchema.properties: params { path + query fields } → --params JSON data { non-file body fields } → --data JSON file { type:file body fields, format:binary } → --file <key>=<path> yes boolean → --yes (only when risk == high-risk-write) Each slot is conditional: only registered when the method actually has fields for that source. This matches the CLI's own conditional flag registration (cmd/service/service.go:170-195), so what AI sees in the schema is exactly what flags exist for that method. The file sub-object carries a description explaining its semantics so AI knows to use --file for those fields rather than embedding the binary in --data JSON. Refresh im.images.create golden (the only file-upload method in the golden set). * test(schema): cover L2 lint recursion into params/data sub-objects Add two negative test cases that stuff bad values inside the wrapped inputSchema sub-objects (rather than at top-level), to lock in walkForL2's recursive coverage: - format:binary on a non-string field nested under params - sub-object Required referencing a key not in its Properties Regression guard so future walkForL2 refactors do not silently lose recursion and let leaf-field violations slip past lint. * fix(schema): coerce example, aggregate nested required, fix path hint - coerce `example` literal to the declared JSON Schema type (rename coerceEnumValue -> coerceLiteral, drop on coerce failure to match the `default` policy). Without this, integer/boolean/number fields emitted string examples and failed strict validators. - aggregate child field `required:true` into the enclosing nested object's `required[]` (both object and array-items shapes). Previously only the top-level params/data sub-objects scanned `required`, so envelopes silently under-reported the real call contract. - check method existence before reporting trailing-segment failure in both JSON and pretty `schema` paths. A typo like `schema im messages typo extra` now reports "Unknown method: im.messages.typo" instead of the misleading "Method 'typo' exists but trailing segments ..." hint. - extract risk level constants (RiskRead / RiskWrite / RiskHighRiskWrite) in internal/cmdutil/risk.go; replace literal usages in schema, lint, and confirm helpers so the typo radius is one file. - reconcile AssembleEnvelope docstring with implementation reality (the package-level currentMethodOrder + assembleMu serialize concurrent callers; output is deterministic per inputs). - drop testdata/golden/ and golden_test harness. End-to-end envelope shape regression now relies on real CLI invocations and the existing property-level unit + lint coverage. * fix(schema): emit items:{} for all typeless arrays, restore lint gate The list→array fallback only added items:{} when the source type was "list", leaving ~64 natively-typed array fields (e.g. approval.instances.cc.cc_user_ids) as {type:"array"} with no items. These violated the L1 lint rule, but TestAllEnvelopesPass skipped the "array missing items" error as a known data inconsistency, so the MCP tool contract was not actually lint-clean. Relax the fallback to cover every array lacking element shape regardless of source type, and drop the lint-test skip so the gate is hard again.	2026-05-27 12:04:01 +08:00
hugang-lark	367cfc9d06	feat: support vc,note,minute event (#1113 )	2026-05-26 22:17:54 +08:00
caojie0621	e182b01f68	feat(drive): add secure label shortcuts (#985 )	2026-05-26 22:06:12 +08:00
SunPeiYang996	1135fc2767	fix: remove unsupported docs fetch text format (#1109 ) Change-Id: I1241ba6feede813c5bfec3e6820bc0886e39dc68	2026-05-26 21:55:42 +08:00
syh-cpdsss	68d78d5067	feat: better whiteboard svg/mermaid instructions (#1097 ) * feat: better whiteboard svg/mermaid instructions Change-Id: I615cdf405840fca6bbaea1f95a37ec655fd6aedf * fix: PR issue Change-Id: I0a8ee556f33f0ba65812a3d73fc9c4a5266abbcd	2026-05-26 21:18:08 +08:00