feat(extension): present restricted commands as absent and trim skills

Integrators that build their own lark-cli distribution can now ship a
package where everything they cut out truly disappears, instead of
lingering as half-disabled stubs that mislead users and agents.

Commands an integrator plugin restricts no longer show up in help or
completion, and invoking one (including asking for its help) answers
"command not included in this build" (subtype command_unavailable) with
no policy vocabulary and no dead-end recovery steering. Integrators can
replace that message with their own product wording via
Rule.DeniedMessage. Cutting a whole domain also retires everything that
points at it: --profile hides and rejects use when the profile domain
goes, the skills-setup footer, update notices, and the auth-login
recovery hint stop rendering when their domains go.

The policy self-inspection commands (config policy show / plugins show)
stay executable by default so operators can still see which rule locked
the build, hidden from help but available on request. Fully-managed
distributions can retire even those with HideDiagnostics().

Plugins can also trim the embedded skills to match: EmbeddedSkills
removes, overlays, or replaces entries over the CLI's built-in set, and
skills list/read plus every help pointer serve the same trimmed tree.

Users who write their own ~/.lark-cli/policy.yml see no change: their
denials stay visible and keep explaining how to adjust the policy they
own. Default builds are byte-for-byte unchanged.

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.67] - 2026-07-08
+
+### Features
+
+- **mail**: add message modify and trash shortcuts (#1567)
+- support whiteboard file inputs in docs XML (#1784)
+- **vc**: refine meeting-events output and reaction forwarding (#1674)
+- **affordance**: usage guidance for shortcuts and per-command skills (#1793)
+
+### Bug Fixes
+
+- accept opaque wiki node tokens (#1789)
+- **apps**: make db --environment optional, auto-select branch server-side (#1735)
+- preserve original filename in multipart file upload (#1767)
+
+### Documentation
+
+- restore one-time authorization guidance in lark-apps skill (#1794)
+
+### Misc
+
+- e2e: harden CLI E2E retry, cleanup, and domain selection (#1709)
+
 ## [v1.0.66] - 2026-07-07
 
 ### Features
@@ -1398,6 +1421,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.67]: https://github.com/larksuite/cli/releases/tag/v1.0.67
 [v1.0.66]: https://github.com/larksuite/cli/releases/tag/v1.0.66
 [v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64

affordance/README.md

@@ -10,18 +10,33 @@ step. Maintain these files alongside `skills/` and `shortcuts/`.
 A small, fixed markdown subset; each file describes one domain:
 
     # <domain>            optional `> skill: <name>` applies to every command below
-    ## <command>          the command as typed, minus `lark-cli <domain>`
+    ## <command>          the command as typed, minus `lark-cli <domain>`; a
+                          +-prefixed heading (## +create) targets that shortcut
     <lead paragraph>      when to use this command
     ### Avoid when        when not to use it / which command to use instead
     ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
     ### Tips              gotchas and constraints
     ### Examples          **description** lines, each followed by a fenced command
+    ### Skills            bullet skill names, or name/relpath references
+                          (lark-contact/references/x.md), to read for usage;
+                          merged with the domain `> skill:` default (deduped,
+                          domain first)
     ### <other heading>   a custom section; flows through verbatim
 
 Reference another command with `[[command]]` — it renders as `command` in help.
 Under `Avoid when` it means "use that one instead"; under `Prerequisites`
 ("… from [[command]]") it means "get the input there first".
 
+Both service-API commands (`## messages get`) and `+`-prefixed shortcuts
+(`## +create`) take entries. A `### Skills` entry is a skill name (validated
+against `<name>/SKILL.md`) or a `name/relpath` reference into that skill
+(validated against the path); help drops any that don't resolve, so a typo shows
+nothing. Point a command at its own reference (e.g. `+search-user` →
+`lark-contact/references/lark-contact-search-user.md`) rather than re-listing the
+domain skill, which the `> skill:` default already covers. When a shortcut also
+sets a hand-authored `Tips` list in Go, the overlay's `### Tips` win — they
+replace the Go tips (not merged), so keep tips in one place.
+
 ## Example
 
     ## messages get
@@ -47,3 +62,5 @@ Under `Avoid when` it means "use that one instead"; under `Prerequisites`
   anything the schema and flags already show; the agent infers the rest.
 - Command-form headings resolve to method ids via the registry, so plural resource
   names (`messages`) map to the singular method id (`message`) automatically.
+  `+`-prefixed shortcut headings are matched verbatim (no plural/space folding),
+  so the heading must equal the shortcut command exactly (`## +history-revert`).

affordance/contact.md

@@ -1,6 +1,42 @@
 # contact
 > skill: lark-contact
 
+## +search-user
+The primary user lookup for user identity: search by keyword or email, resolve known ids with --user-ids, or get yourself with --user-ids me — it does by-id reads too, so as a user you rarely need `+get-user`. Each match returns an open_id and p2p_chat_id to chain into follow-ups.
+
+### Skills
+- lark-contact/references/lark-contact-search-user.md
+
+### Avoid when
+- Running as a bot — this shortcut is user-only; use [[+get-user]] instead (it supports bot identity)
+- You only need users' personal status for ids you already hold → use [[user_profiles batch_query]]
+
+### Examples
+
+**Find a user by name**
+```bash
+lark-cli contact +search-user --query "alice" --as user
+```
+
+**Fetch known users by open_id (me = yourself)**
+```bash
+lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
+```
+
+## +get-user
+Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
+
+### Skills
+- lark-contact/references/lark-contact-get-user.md
+
+### Avoid when
+- You don't have the user's id yet, or want to match by name/keyword → use [[+search-user]]
+- Running as a user — [[+search-user]] --user-ids covers by-id reads and more in one tool
+
+### Tips
+- Self lookup (omit --user-id) needs user identity; a bot must pass --user-id
+- --user-id-type must match the id you pass (default open_id)
+
 ## user_profiles batch_query
 Bulk-fetch personal status and signature for user ids you already have.
 

cmd/api/api_test.go

@@ -4,10 +4,14 @@
 package api
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
+	"mime"
+	"mime/multipart"
 	"os"
+	"path/filepath"
 	"sort"
 	"strings"
 	"testing"
@@ -1069,3 +1073,157 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 		t.Errorf("expected method GET, got %s", gotOpts.Method)
 	}
 }
+
+// parseMultipartFilenames drives one api --file upload through the mock
+// transport and returns a map of field name -> part filename parsed from the
+// captured multipart body, plus the map of text form fields. It fails the test
+// if the captured request is not multipart/form-data.
+func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) (map[string]string, map[string]string) {
+	t.Helper()
+	ct := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(ct)
+	if err != nil {
+		t.Fatalf("parse Content-Type %q: %v", ct, err)
+	}
+	if !strings.HasPrefix(mediaType, "multipart/") {
+		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
+	}
+	filenames := map[string]string{}
+	fields := map[string]string{}
+	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	for {
+		part, err := mr.NextPart()
+		if err != nil {
+			break
+		}
+		if fn := part.FileName(); fn != "" {
+			filenames[part.FormName()] = fn
+		} else {
+			buf := &bytes.Buffer{}
+			_, _ = buf.ReadFrom(part)
+			fields[part.FormName()] = buf.String()
+		}
+	}
+	return filenames, fields
+}
+
+func TestApiCmd_FileUpload_PreservesFilename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "invoice.pdf"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "invoice.pdf" {
+		t.Fatalf("part filename for field %q = %q, want %q", "file", got, "invoice.pdf")
+	}
+}
+
+func TestApiCmd_FileUpload_FieldPrefixKeepsBasename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0700); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "sub", "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "upload=sub/invoice.pdf"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if _, ok := filenames["upload"]; !ok {
+		t.Fatalf("expected field name %q from field=path form, got fields %v", "upload", filenames)
+	}
+	if got := filenames["upload"]; got != "invoice.pdf" {
+		t.Fatalf("part filename for field %q = %q, want %q (basename only)", "upload", got, "invoice.pdf")
+	}
+}
+
+func TestApiCmd_FileUpload_WithDataFields(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot",
+		"--file", "invoice.pdf", "--data", `{"type":"attachment"}`})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, fields := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "invoice.pdf" {
+		t.Fatalf("part filename = %q, want %q", got, "invoice.pdf")
+	}
+	if got := fields["type"]; got != "attachment" {
+		t.Fatalf("text field type = %q, want %q", got, "attachment")
+	}
+}
+
+func TestApiCmd_FileUpload_StdinFallsBackToUnknown(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	})
+	f.IOStreams.In = bytes.NewReader([]byte("stdin-bytes"))
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/approval/v4/files/upload",
+		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdApi(f, nil)
+	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "-"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames, _ := parseMultipartFilenames(t, stub)
+	if got := filenames["file"]; got != "unknown-file" {
+		t.Fatalf("stdin part filename = %q, want %q (no stable local name, fallback)", got, "unknown-file")
+	}
+}

cmd/build.go

@@ -21,12 +21,16 @@ import (
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	"github.com/larksuite/cli/cmd/whoami"
 	_ "github.com/larksuite/cli/events"
+	"github.com/larksuite/cli/extension/platform"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
+	internalplatform "github.com/larksuite/cli/internal/platform"
+	"github.com/larksuite/cli/internal/policystate"
+	"github.com/larksuite/cli/internal/skillpolicy"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -42,6 +46,7 @@ type buildConfig struct {
 	skipStrictMode bool
 	skipService    bool
 	serviceCatalog *apicatalog.Catalog
+	skillsOverlay  *platform.SkillsOverlay
 }
 
 // WithIO sets the IO streams for the CLI by wrapping raw reader/writers.
@@ -59,6 +64,17 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }
 
+// WithEmbeddedSkills customizes the CLI's embedded skills for a caller that builds
+// the command tree directly instead of registering a plugin. It is the
+// build-option analogue of a plugin's EmbeddedSkills(...): the same single-owner
+// rule applies, so combining WithEmbeddedSkills with a plugin that also customizes
+// skills aborts startup. nil is a no-op.
+func WithEmbeddedSkills(spec *platform.SkillsOverlay) BuildOption {
+	return func(c *buildConfig) {
+		c.skillsOverlay = spec
+	}
+}
+
 // embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
 // at build time. It is registered by the repo-root package main's init via
 // SetEmbeddedSkillContent — it cannot be threaded through main.go without
@@ -71,6 +87,21 @@ var embeddedSkillContent fs.FS
 // supply its own skill content.
 func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
 
+// withEmbeddedSkillsOwner labels a WithEmbeddedSkills contribution in the skill resolver so a
+// WithEmbeddedSkills + plugin-Skills collision names a stable, non-plugin owner.
+const withEmbeddedSkillsOwner = "cmd.WithEmbeddedSkills"
+
+// resolveSkillContent composes the effective embedded skill tree from the CLI
+// default, an optional WithEmbeddedSkills spec, and plugin SkillsOverlays, enforcing the
+// single-owner rule across all sources.
+func resolveSkillContent(cfg *buildConfig, pluginSkills []skillpolicy.PluginSkill) (fs.FS, error) {
+	sources := pluginSkills
+	if cfg.skillsOverlay != nil {
+		sources = append([]skillpolicy.PluginSkill{{PluginName: withEmbeddedSkillsOwner, SkillsOverlay: cfg.skillsOverlay}}, sources...)
+	}
+	return skillpolicy.Resolve(embeddedSkillContent, sources)
+}
+
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -154,6 +185,14 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 		cfg.streams = cmdutil.SystemIO()
 	}
 
+	// Reset every process-global snapshot up front, not only inside
+	// applyUserPolicyPruning: the skipPlugins and install-failure paths
+	// return before pruning runs, and a previous build's state must not
+	// leak into this one (long-lived embedders, test sequences).
+	policystate.SetPluginDeniedDomains(nil)
+	cmdpolicy.SetActive(nil)
+	internalplatform.SetActiveInventory(nil)
+
 	f := cmdutil.NewDefault(cfg.streams, inv)
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
@@ -175,7 +214,16 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	// rootUsageTemplate.
 	rootCmd.SetUsageTemplate(rootUsageTemplate)
 
-	installTipsHelpFunc(rootCmd)
+	// The skill-content getter also gates on the skills command domain:
+	// every pointer it feeds renders as `lark-cli skills read ...`, so with
+	// that domain plugin-denied the pointers would all be dead ends even
+	// though the content itself still exists.
+	installTipsHelpFunc(rootCmd, func() fs.FS {
+		if policystate.DomainDeniedByPlugin("skills") {
+			return nil
+		}
+		return f.SkillContent
+	})
 	rootCmd.SilenceErrors = true
 	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
 	// covers flag-parse errors, which fail before PreRun runs — otherwise cobra
@@ -223,6 +271,13 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	}
 
 	if cfg.skipPlugins {
+		installHelpCommand(rootCmd)
+		resolved, err := resolveSkillContent(cfg, nil)
+		if err != nil {
+			installPluginSkillErrorGuard(rootCmd, err)
+			return f, rootCmd, nil
+		}
+		f.SkillContent = resolved
 		recordInventory(nil)
 		return f, rootCmd, nil
 	}
@@ -233,23 +288,52 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 		return f, rootCmd, nil
 	}
 	var pluginRules []cmdpolicy.PluginRule
+	var pluginSkills []skillpolicy.PluginSkill
 	var registry *hook.Registry
 	if installResult != nil {
 		pluginRules = installResult.PluginRules
+		pluginSkills = installResult.PluginSkills
 		registry = installResult.Registry
 	}
 
 	// Policy errors fail-CLOSED when a plugin contributed (security
 	// intent must not be silently dropped); yaml-only errors fail-OPEN
 	// with a warning so a typo can't lock the user out.
-	if err := applyUserPolicyPruning(rootCmd, pluginRules); err != nil {
+	denied, policyErr := applyUserPolicyPruning(rootCmd, pluginRules)
+	if policyErr != nil {
 		if len(pluginRules) > 0 {
-			installPluginConflictGuard(rootCmd, err)
+			installPluginConflictGuard(rootCmd, policyErr)
 			return f, rootCmd, nil
 		}
-		warnPolicyError(cfg.streams.ErrOut, err)
+		warnPolicyError(cfg.streams.ErrOut, policyErr)
 	}
 
+	// The custom help command attaches AFTER policy evaluation on purpose:
+	// it is a framework meta command, and inside the evaluated tree an
+	// allow-list rule (Allow: ["im/**"]) would deny it as
+	// domain_not_allowed — cobra's stock help command is likewise attached
+	// only at Execute time and never evaluated.
+	installHelpCommand(rootCmd)
+
+	// Presentation passes: a capability an integrator plugin denied
+	// presents as absent — retired global flags (--profile), no skills
+	// footer, diagnostics hidden or retired. Enforcement stays with
+	// cmdpolicy.Apply above; these only shape help and fixed hints.
+	applyPluginPresentation(rootCmd, installResult, denied)
+
+	// Resolve the embedded skill tree BEFORE wiring hooks: an invalid
+	// SkillsOverlay must fail fast, before wireHooks emits Startup, so a Startup
+	// side effect is never stranded without its Shutdown. Both skill readers
+	// -- `skills list`/`read` and the --help guidance -- then read this one
+	// f.SkillContent. Fails closed: never silently ship defaults once a
+	// customization is declared.
+	resolvedSkills, skillErr := resolveSkillContent(cfg, pluginSkills)
+	if skillErr != nil {
+		installPluginSkillErrorGuard(rootCmd, skillErr)
+		return f, rootCmd, nil
+	}
+	f.SkillContent = resolvedSkills
+
 	if registry != nil {
 		if err := wireHooks(ctx, rootCmd, registry); err != nil {
 			installPluginLifecycleErrorGuard(rootCmd, err)

cmd/config/config_test.go

@@ -20,6 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 )
 
 type noopConfigKeychain struct{}
@@ -564,3 +565,54 @@ func TestPrintLangPreferenceConfirmation(t *testing.T) {
 		}
 	})
 }
+
+// The "no active profile" hint points at `lark-cli profile list`; that pointer
+// must be gated on the profile domain still being present. When a plugin denies
+// the profile domain, the hint would be a dead end, so it is omitted — the error
+// itself is unchanged.
+func TestConfigShowRun_ProfileHintGatedByPluginDenial(t *testing.T) {
+	multi := &core.MultiAppConfig{
+		CurrentApp: "missing",
+		Apps: []core.AppConfig{{
+			Name:      "default",
+			AppId:     "app-default",
+			AppSecret: core.PlainSecret("secret-default"),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+
+	hintOf := func(t *testing.T) string {
+		t.Helper()
+		t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+		if err := core.SaveMultiAppConfig(multi); err != nil {
+			t.Fatalf("SaveMultiAppConfig() error = %v", err)
+		}
+		f, _, _, _ := cmdutil.TestFactory(t, nil)
+		err := configShowRun(&ConfigShowOptions{Factory: f})
+		var cfgErr *errs.ConfigError
+		if !errors.As(err, &cfgErr) {
+			t.Fatalf("expected *errs.ConfigError, got %T %v", err, err)
+		}
+		if cfgErr.Subtype != errs.SubtypeNotConfigured {
+			t.Fatalf("subtype = %q, want not_configured", cfgErr.Subtype)
+		}
+		return cfgErr.Hint
+	}
+
+	t.Run("profile domain present: hint points at profile list", func(t *testing.T) {
+		policystate.ResetForTesting()
+		t.Cleanup(policystate.ResetForTesting)
+		if h := hintOf(t); !strings.Contains(h, "lark-cli profile list") {
+			t.Errorf("hint = %q, want it to reference `lark-cli profile list`", h)
+		}
+	})
+
+	t.Run("profile domain plugin-denied: hint omitted", func(t *testing.T) {
+		policystate.ResetForTesting()
+		t.Cleanup(policystate.ResetForTesting)
+		policystate.SetPluginDeniedDomains(map[string]bool{"profile": true})
+		if h := hintOf(t); h != "" {
+			t.Errorf("hint = %q, want empty when the profile domain is plugin-denied", h)
+		}
+	})
+}

cmd/config/plugins.go

@@ -85,6 +85,9 @@ func runConfigPluginsShow(f *cmdutil.Factory) error {
 		if len(p.Rules) > 0 {
 			entry["rules"] = p.Rules
 		}
+		if p.EmbeddedSkills != nil {
+			entry["embedded_skills"] = p.EmbeddedSkills
+		}
 		entry["hooks"] = map[string]any{
 			"observers": p.Observers,
 			"wrappers":  p.Wrappers,

cmd/config/plugins_test.go

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	internalplatform "github.com/larksuite/cli/internal/platform"
+)
+
+// config plugins show must surface a plugin's EmbeddedSkills contribution in
+// the rendered JSON, not only in the internal inventory struct: this command is
+// the operator's window into what a fork trimmed, so the Allow/Remove/Overlay/
+// Base summary has to reach stdout. Guards the render layer, which asserting the
+// inventory struct alone does not exercise.
+func TestConfigPluginsShow_RendersEmbeddedSkills(t *testing.T) {
+	internalplatform.SetActiveInventory(&internalplatform.Inventory{
+		Plugins: []internalplatform.PluginEntry{{
+			Name:         "acme",
+			Version:      "1.0",
+			Capabilities: internalplatform.CapabilitiesView{Restricts: true, FailurePolicy: "fail-closed"},
+			EmbeddedSkills: &internalplatform.SkillsOverlayView{
+				Allow:   []string{"lark-im"},
+				Remove:  []string{"lark-a"},
+				Overlay: true,
+				Base:    true,
+			},
+		}},
+	})
+	t.Cleanup(func() { internalplatform.SetActiveInventory(nil) })
+
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{IOStreams: cmdutil.NewIOStreams(nil, out, &bytes.Buffer{})}
+	if err := runConfigPluginsShow(f); err != nil {
+		t.Fatalf("show: %v", err)
+	}
+
+	var got struct {
+		Plugins []struct {
+			EmbeddedSkills *internalplatform.SkillsOverlayView `json:"embedded_skills"`
+		} `json:"plugins"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("not json: %v\n%s", err, out.String())
+	}
+	if len(got.Plugins) != 1 {
+		t.Fatalf("want 1 plugin, got %d", len(got.Plugins))
+	}
+	es := got.Plugins[0].EmbeddedSkills
+	if es == nil {
+		t.Fatalf("embedded_skills missing from rendered output:\n%s", out.String())
+	}
+	if len(es.Allow) != 1 || es.Allow[0] != "lark-im" ||
+		len(es.Remove) != 1 || es.Remove[0] != "lark-a" ||
+		!es.Overlay || !es.Base {
+		t.Errorf("embedded_skills summary mismatch: %+v", es)
+	}
+}
+
+// A plugin that did not customize embedded skills must not emit an
+// embedded_skills key, so the field's presence is a reliable signal that a fork
+// trimmed the tree.
+func TestConfigPluginsShow_OmitsEmbeddedSkillsWhenAbsent(t *testing.T) {
+	internalplatform.SetActiveInventory(&internalplatform.Inventory{
+		Plugins: []internalplatform.PluginEntry{{
+			Name:         "acme",
+			Version:      "1.0",
+			Capabilities: internalplatform.CapabilitiesView{Restricts: true, FailurePolicy: "fail-closed"},
+		}},
+	})
+	t.Cleanup(func() { internalplatform.SetActiveInventory(nil) })
+
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{IOStreams: cmdutil.NewIOStreams(nil, out, &bytes.Buffer{})}
+	if err := runConfigPluginsShow(f); err != nil {
+		t.Fatalf("show: %v", err)
+	}
+	var raw map[string]any
+	if err := json.Unmarshal(out.Bytes(), &raw); err != nil {
+		t.Fatalf("not json: %v", err)
+	}
+	plugins, ok := raw["plugins"].([]any)
+	if !ok || len(plugins) != 1 {
+		t.Fatalf("want 1 plugin in output, got: %s", out.String())
+	}
+	if _, ok := plugins[0].(map[string]any)["embedded_skills"]; ok {
+		t.Errorf("embedded_skills must be omitted when the plugin customized no skills; got:\n%s", out.String())
+	}
+}

cmd/config/show.go

@@ -13,6 +13,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 	"github.com/spf13/cobra"
 )
 
@@ -55,7 +56,12 @@ func configShowRun(opts *ConfigShowOptions) error {
 	}
 	app := config.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil {
-		return errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile").WithHint("run: lark-cli profile list")
+		e := errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile")
+		// No recovery hint when the profile domain is absent from this build.
+		if !policystate.DomainDeniedByPlugin("profile") {
+			e = e.WithHint("run: lark-cli profile list")
+		}
+		return e
 	}
 	users := "(no logged-in users)"
 	if len(app.Users) > 0 {

cmd/flag_gate.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdpolicy"
+)
+
+// globalFlagDomains maps each root persistent flag to the command domain
+// it belongs to. A new domain-tied global flag must add a row.
+var globalFlagDomains = map[string]string{
+	"profile": "profile",
+}
+
+// flagGateAnnotation distinguishes a policy-retired flag from one hidden
+// cosmetically (single-app mode force-shows the latter in root help).
+const flagGateAnnotation = "lark:policy_denied_flag"
+
+// applyPluginFlagGate hides and rejects the global flags whose whole
+// domain a plugin denied. yaml denials do not gate flags. Must run after
+// RegisterGlobalFlags and cmdpolicy.Apply.
+func applyPluginFlagGate(root *cobra.Command, denied map[string]cmdpolicy.Denial) {
+	gated := false
+	for flagName, domain := range globalFlagDomains {
+		d, ok := denied[domain]
+		if !ok || !cmdpolicy.IsPluginPolicySource(d.PolicySource) {
+			continue
+		}
+		fl := root.PersistentFlags().Lookup(flagName)
+		if fl == nil {
+			continue
+		}
+		fl.Hidden = true
+		if fl.Annotations == nil {
+			fl.Annotations = map[string][]string{}
+		}
+		fl.Annotations[flagGateAnnotation] = []string{"true"}
+		gated = true
+	}
+	if gated {
+		installFlagGateRejection(root)
+	}
+}
+
+func isPolicyGatedFlag(fl *pflag.Flag) bool {
+	return fl != nil && fl.Annotations[flagGateAnnotation] != nil
+}
+
+// installFlagGateRejection rejects gated flags right after parsing.
+// pflag has no runtime unregister, so the flag still parses; and cobra
+// resolves PersistentPreRunE "first non-nil wins" walking up from the
+// leaf, so every command carrying its own (cmd/auth, cmd/config) must be
+// wrapped too, not just the root.
+func installFlagGateRejection(root *cobra.Command) {
+	var walk func(c *cobra.Command)
+	walk = func(c *cobra.Command) {
+		if prev := c.PersistentPreRunE; prev != nil {
+			c.PersistentPreRunE = func(cc *cobra.Command, args []string) error {
+				if err := rejectGatedFlags(cc); err != nil {
+					return err
+				}
+				return prev(cc, args)
+			}
+		}
+		for _, child := range c.Commands() {
+			walk(child)
+		}
+	}
+	prevRun := root.PersistentPreRun
+	root.PersistentPreRun = nil
+	root.PersistentPreRunE = func(c *cobra.Command, args []string) error {
+		if err := rejectGatedFlags(c); err != nil {
+			return err
+		}
+		if prevRun != nil {
+			prevRun(c, args)
+		}
+		return nil
+	}
+	for _, child := range root.Commands() {
+		walk(child)
+	}
+}
+
+// rejectGatedFlags fails a set policy-retired flag with the same shape an
+// unregistered flag produces (see flagDidYouMean).
+//
+// VisitAll + fl.Changed, not Visit: cobra parses a persistent flag on the leaf
+// command's merged flagset, so root.PersistentFlags()'s "changed" table stays
+// empty and Visit (which only walks that table) never fires on the dispatch
+// path. The flag objects are shared by pointer across the merge, so fl.Changed
+// reflects a real leaf-level parse.
+func rejectGatedFlags(c *cobra.Command) error {
+	var rejected error
+	c.Root().PersistentFlags().VisitAll(func(fl *pflag.Flag) {
+		if rejected == nil && fl.Changed && isPolicyGatedFlag(fl) {
+			rejected = errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"unknown flag %q for %q", "--"+fl.Name, c.CommandPath()).
+				WithParams(errs.InvalidParam{Name: "--" + fl.Name, Reason: "unknown flag"}).
+				WithHint("run `%s --help` to see valid flags", c.CommandPath())
+		}
+	})
+	return rejected
+}

cmd/platform_bootstrap.go

@@ -17,6 +17,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/hook"
 	internalplatform "github.com/larksuite/cli/internal/platform"
+	"github.com/larksuite/cli/internal/policystate"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -35,7 +36,15 @@ const userPolicyFileName = "policy.yml"
 //
 // pluginRules carries Plugin.Restrict() contributions collected from
 // the InstallAll phase; nil/empty is fine.
-func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) error {
+//
+// The returned denied map (nil when no rule denied anything) feeds the
+// post-pruning presentation passes in build.go: the global-flag gate and
+// the fixed-hint filter both key off which domains a plugin denied.
+func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) (map[string]cmdpolicy.Denial, error) {
+	// Reset up front so every early return leaves the process-global
+	// snapshot clean; the success path re-populates it.
+	policystate.SetPluginDeniedDomains(nil)
+
 	// Plugin rules shadow the yaml source entirely (Resolve: plugin >
 	// yaml). When a plugin contributed rules we therefore do NOT even
 	// read ~/.lark-cli/policy.yml: build.go fail-CLOSES on any policy
@@ -65,7 +74,7 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 			// show` reports "no policy" instead of a stale rule that
 			// doesn't reflect the current command tree.
 			cmdpolicy.SetActive(nil)
-			return lerr
+			return nil, lerr
 		}
 		yamlRules = loaded
 	}
@@ -77,11 +86,11 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 	})
 	if err != nil {
 		cmdpolicy.SetActive(nil)
-		return err
+		return nil, err
 	}
 	if len(rules) == 0 {
 		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
-		return nil
+		return nil, nil
 	}
 
 	// RuleName attributes a denial to a specific rule in the envelope.
@@ -94,17 +103,39 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 		ruleName = rules[0].Name
 	}
 
+	// DeniedMessage is build-level: the first non-empty message across
+	// the single owner's rules speaks for all of them.
+	deniedMessage := ""
+	for _, r := range rules {
+		if r.DeniedMessage != "" {
+			deniedMessage = r.DeniedMessage
+			break
+		}
+	}
+
 	engine := cmdpolicy.NewSet(rules)
 	decisions := engine.EvaluateAll(rootCmd)
-	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName)
+	denied := cmdpolicy.BuildDeniedByPath(rootCmd, decisions, source, ruleName, deniedMessage)
 	cmdpolicy.Apply(rootCmd, denied)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules:       rules,
-		Source:      source,
-		DeniedPaths: len(denied),
+		Rules:        rules,
+		Source:       source,
+		DeniedPaths:  len(denied),
+		DeniedByPath: denied,
 	})
-	return nil
+
+	// Whole-domain denials surface as aggregate entries keyed by the
+	// bare domain name (no slash); record them for render-time hint
+	// emitters (internal/auth, internal/client, the notice provider).
+	pluginDomains := map[string]bool{}
+	for path, d := range denied {
+		if !strings.Contains(path, "/") && cmdpolicy.IsPluginPolicySource(d.PolicySource) {
+			pluginDomains[path] = true
+		}
+	}
+	policystate.SetPluginDeniedDomains(pluginDomains)
+	return denied, nil
 }
 
 // installPluginsAndHooks runs the InstallAll phase on the globally-
@@ -156,7 +187,22 @@ func recordInventory(installResult *internalplatform.InstallResult) {
 			AllowUnannotated: r.Rule.AllowUnannotated,
 		})
 	}
-	internalplatform.SetActiveInventory(internalplatform.BuildInventory(pluginSrcs, installResult.Registry, ruleSrcs))
+	skillSrcs := make([]internalplatform.SkillsInventorySource, 0, len(installResult.PluginSkills))
+	for _, ps := range installResult.PluginSkills {
+		if ps.SkillsOverlay == nil {
+			continue
+		}
+		skillSrcs = append(skillSrcs, internalplatform.SkillsInventorySource{
+			PluginName: ps.PluginName,
+			View: internalplatform.SkillsOverlayView{
+				Allow:   ps.SkillsOverlay.Allow,
+				Remove:  ps.SkillsOverlay.Remove,
+				Overlay: ps.SkillsOverlay.Overlay != nil,
+				Base:    ps.SkillsOverlay.Base != nil,
+			},
+		})
+	}
+	internalplatform.SetActiveInventory(internalplatform.BuildInventory(pluginSrcs, installResult.Registry, ruleSrcs, skillSrcs))
 }
 
 // wireHooks installs Observer/Wrapper hooks onto every runnable command

cmd/platform_bootstrap_test.go

@@ -116,7 +116,7 @@ max_risk: write
 `)
 
 	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, nil); err != nil {
+	if _, err := applyUserPolicyPruning(root, nil); err != nil {
 		t.Fatalf("apply policy: %v", err)
 	}
 
@@ -175,7 +175,7 @@ func TestApplyUserPolicyPruning_missingFileIsSilent(t *testing.T) {
 	tmpHome(t) // home set but no policy.yml written
 
 	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, nil); err != nil {
+	if _, err := applyUserPolicyPruning(root, nil); err != nil {
 		t.Fatalf("missing policy should not error, got %v", err)
 	}
 
@@ -196,7 +196,7 @@ func TestApplyUserPolicyPruning_malformedYamlReturnsError(t *testing.T) {
 	writePolicy(t, cfgDir, "::: not yaml :::")
 
 	root := fakeTree(t)
-	err := applyUserPolicyPruning(root, nil)
+	_, err := applyUserPolicyPruning(root, nil)
 	if err == nil {
 		t.Fatalf("malformed yaml should produce an error")
 	}
@@ -221,7 +221,7 @@ func TestApplyUserPolicyPruning_pluginRulesSkipBrokenYaml(t *testing.T) {
 		}},
 	}
 	root := fakeTree(t)
-	if err := applyUserPolicyPruning(root, pluginRules); err != nil {
+	if _, err := applyUserPolicyPruning(root, pluginRules); err != nil {
 		t.Fatalf("plugin rules must shadow (and skip reading) yaml; broken yaml should not error, got %v", err)
 	}
 
@@ -243,7 +243,7 @@ func TestApplyUserPolicyPruning_invalidRuleReturnsError(t *testing.T) {
 	writePolicy(t, cfgDir, "max_risk: nukem\n")
 
 	root := fakeTree(t)
-	err := applyUserPolicyPruning(root, nil)
+	_, err := applyUserPolicyPruning(root, nil)
 	if err == nil {
 		t.Fatalf("invalid MaxRisk should produce an error")
 	}

cmd/platform_guards.go

@@ -12,6 +12,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/hook"
 	internalplatform "github.com/larksuite/cli/internal/platform"
+	"github.com/larksuite/cli/internal/skillpolicy"
 )
 
 // installFatalGuard wires a fail-closed guard at every cobra dispatch
@@ -110,6 +111,27 @@ func installPluginConflictGuard(rootCmd *cobra.Command, err error) {
 	installFatalGuard(rootCmd, makeErr)
 }
 
+// installPluginSkillErrorGuard surfaces a plugin SkillsOverlay configuration
+// error before any command runs. Two failure modes, split by reason code:
+//
+//   - "invalid_skills_overlay"          - a Remove/Overlay that cannot compose
+//   - "multiple_skills_overlay_plugins" - two plugins each customizing skills
+//
+// The CLI must NOT silently fall back to default skills once an
+// integrator has declared a customization.
+func installPluginSkillErrorGuard(rootCmd *cobra.Command, err error) {
+	makeErr := func() error {
+		reasonCode := internalplatform.ReasonInvalidSkillsOverlay
+		if errors.Is(err, skillpolicy.ErrMultipleSkillsOverlays) {
+			reasonCode = internalplatform.ReasonMultipleSkillsOverlays
+		}
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "%s", err.Error()).
+			WithHint("plugin skill customization is broken (reason_code %s); fix the plugin's SkillsOverlay or remove the conflicting plugin", reasonCode).
+			WithCause(err)
+	}
+	installFatalGuard(rootCmd, makeErr)
+}
+
 // installPluginLifecycleErrorGuard surfaces a Startup lifecycle handler
 // failure as a typed validation error (failed_precondition). The hint's
 // reason code splits returned-error vs panic so consumers (audit /

cmd/presentation.go

@@ -0,0 +1,169 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdpolicy"
+	internalplatform "github.com/larksuite/cli/internal/platform"
+)
+
+// applyPluginPresentation makes plugin-denied capabilities present as
+// absent: retired flags, no skills footer, diagnostics hidden or retired.
+// Presentation only — enforcement happened in cmdpolicy.Apply.
+func applyPluginPresentation(rootCmd *cobra.Command, installResult *internalplatform.InstallResult, denied map[string]cmdpolicy.Denial) {
+	applyPluginFlagGate(rootCmd, denied)
+
+	if domainDeniedByPlugin(denied, "skills") {
+		rootCmd.SetUsageTemplate(strings.Replace(rootUsageTemplate, skillsSetupFooter, "", 1))
+	}
+
+	if installResult != nil && hideDiagnosticsOwner(installResult.Plugins) != "" {
+		retireDiagnostics(rootCmd, installResult, denied)
+	} else {
+		concealDiagnostics(rootCmd, denied)
+	}
+}
+
+// domainDeniedByPlugin reads the freshly-built denied map, unlike
+// policystate.DomainDeniedByPlugin which serves render-time consumers.
+func domainDeniedByPlugin(denied map[string]cmdpolicy.Denial, domain string) bool {
+	d, ok := denied[domain]
+	return ok && cmdpolicy.IsPluginPolicySource(d.PolicySource)
+}
+
+// hideDiagnosticsOwner returns the plugin that declared HideDiagnostics,
+// or "". The host already enforced that it also Restricts.
+func hideDiagnosticsOwner(plugins []internalplatform.PluginInfo) string {
+	for _, p := range plugins {
+		if p.Capabilities.HideDiagnostics {
+			return p.Name
+		}
+	}
+	return ""
+}
+
+// retireDiagnostics installs the unavailable presentation on the
+// diagnostic exemptions, same as any other plugin-denied command.
+func retireDiagnostics(rootCmd *cobra.Command, installResult *internalplatform.InstallResult, denied map[string]cmdpolicy.Denial) {
+	source := "plugin:" + hideDiagnosticsOwner(installResult.Plugins)
+	message := ""
+	for _, d := range denied {
+		if cmdpolicy.IsPluginPolicySource(d.PolicySource) && d.DeniedMessage != "" {
+			message = d.DeniedMessage
+			break
+		}
+	}
+	diag := map[string]cmdpolicy.Denial{}
+	for _, path := range cmdpolicy.DiagnosticPaths() {
+		diag[path] = cmdpolicy.Denial{
+			Layer:         cmdpolicy.LayerPolicy,
+			PolicySource:  source,
+			ReasonCode:    "diagnostics_hidden",
+			Reason:        "policy self-inspection hidden by the integrator",
+			DeniedMessage: message,
+		}
+	}
+	cmdpolicy.Apply(rootCmd, diag)
+}
+
+// concealDiagnostics hides the diagnostic exemptions from help — without
+// touching their RunE, so they stay dispatchable — once every non-exempt
+// sibling in their domain is already hidden. The group itself then gets
+// the unavailable stub: it escaped denial aggregation only because the
+// exemptions kept a runnable descendant alive, and its unknown-subcommand
+// guard RunE would otherwise keep it listed in help.
+func concealDiagnostics(rootCmd *cobra.Command, denied map[string]cmdpolicy.Denial) {
+	for _, group := range diagnosticDomainGroups(rootCmd) {
+		if !pluginDeniedUnder(denied, cmdpolicy.CanonicalPath(group)) {
+			continue
+		}
+		exemptAncestors := map[*cobra.Command]bool{}
+		for _, path := range cmdpolicy.DiagnosticPaths() {
+			for c := findByPath(rootCmd, path); c != nil && c != group; c = c.Parent() {
+				exemptAncestors[c] = true
+			}
+		}
+		allOthersHidden := true
+		for _, child := range group.Commands() {
+			if child.Name() == "help" || exemptAncestors[child] {
+				continue
+			}
+			if !child.Hidden {
+				allOthersHidden = false
+				break
+			}
+		}
+		if !allOthersHidden {
+			continue
+		}
+		for c := range exemptAncestors {
+			c.Hidden = true
+		}
+		var sample cmdpolicy.Denial
+		for path, d := range denied {
+			if strings.HasPrefix(path, cmdpolicy.CanonicalPath(group)+"/") && cmdpolicy.IsPluginPolicySource(d.PolicySource) {
+				sample = d
+				break
+			}
+		}
+		cmdpolicy.Apply(rootCmd, map[string]cmdpolicy.Denial{
+			cmdpolicy.CanonicalPath(group): {
+				Layer:         cmdpolicy.LayerPolicy,
+				PolicySource:  sample.PolicySource,
+				RuleName:      sample.RuleName,
+				ReasonCode:    "all_children_denied",
+				Reason:        "all child commands are denied",
+				DeniedMessage: sample.DeniedMessage,
+			},
+		})
+	}
+}
+
+// diagnosticDomainGroups returns the top-level groups containing a
+// diagnostic exemption (today just `config`).
+func diagnosticDomainGroups(rootCmd *cobra.Command) []*cobra.Command {
+	seen := map[*cobra.Command]bool{}
+	var out []*cobra.Command
+	for _, path := range cmdpolicy.DiagnosticPaths() {
+		top, _, _ := strings.Cut(path, "/")
+		if c := findByPath(rootCmd, top); c != nil && !seen[c] {
+			seen[c] = true
+			out = append(out, c)
+		}
+	}
+	return out
+}
+
+func pluginDeniedUnder(denied map[string]cmdpolicy.Denial, prefix string) bool {
+	for path, d := range denied {
+		if strings.HasPrefix(path, prefix+"/") && cmdpolicy.IsPluginPolicySource(d.PolicySource) {
+			return true
+		}
+	}
+	return false
+}
+
+// findByPath resolves a canonical slash path (e.g. "config/policy/show")
+// to the command node, or nil.
+func findByPath(rootCmd *cobra.Command, path string) *cobra.Command {
+	cur := rootCmd
+	for _, seg := range strings.Split(path, "/") {
+		var next *cobra.Command
+		for _, child := range cur.Commands() {
+			if child.Name() == seg {
+				next = child
+				break
+			}
+		}
+		if next == nil {
+			return nil
+		}
+		cur = next
+	}
+	return cur
+}

cmd/presentation_test.go

@@ -0,0 +1,397 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/platform"
+	"github.com/larksuite/cli/internal/cmdpolicy"
+	internalplatform "github.com/larksuite/cli/internal/platform"
+	"github.com/larksuite/cli/internal/policystate"
+	"github.com/larksuite/cli/internal/update"
+)
+
+// restrictingPlugin registers a plugin that denies the given globs; extra
+// customizes the builder further (nil for none).
+func restrictingPlugin(t *testing.T, deny []string, extra func(*platform.Builder) *platform.Builder) {
+	t.Helper()
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+	t.Cleanup(func() { policystate.ResetForTesting() })
+	b := platform.NewPlugin("acme", "1.0").Restrict(&platform.Rule{Deny: deny})
+	if extra != nil {
+		b = extra(b)
+	}
+	platform.Register(b.MustBuild())
+}
+
+// runnableUnder returns the first runnable non-exempt descendant under
+// the named top-level group of the real command tree (the diagnostic
+// exemptions keep their original RunE and would not exercise the stub).
+func runnableUnder(t *testing.T, root *cobra.Command, group string) *cobra.Command {
+	t.Helper()
+	g := findByPath(root, group)
+	if g == nil {
+		t.Fatalf("group %q not found in command tree", group)
+	}
+	var find func(c *cobra.Command) *cobra.Command
+	find = func(c *cobra.Command) *cobra.Command {
+		if c.RunE != nil && len(c.Commands()) == 0 && !cmdpolicy.IsDiagnosticPath(cmdpolicy.CanonicalPath(c)) {
+			return c
+		}
+		for _, child := range c.Commands() {
+			if leaf := find(child); leaf != nil {
+				return leaf
+			}
+		}
+		return nil
+	}
+	leaf := find(g)
+	if leaf == nil {
+		t.Fatalf("no runnable non-exempt leaf under %q", group)
+	}
+	return leaf
+}
+
+// A plugin-denied command answers with command_unavailable: default
+// message, no hint, no policy vocabulary.
+func TestBuildInternal_pluginDenyPresentsUnavailable(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	leaf := runnableUnder(t, root, "config")
+
+	err := leaf.RunE(leaf, nil)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
+	}
+	if ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("subtype = %q, want command_unavailable", ve.Subtype)
+	}
+	if ve.Message != cmdpolicy.DefaultUnavailableMessage || ve.Hint != "" {
+		t.Errorf("message=%q hint=%q, want default message and empty hint", ve.Message, ve.Hint)
+	}
+}
+
+// Rule.DeniedMessage speaks in the integrator's product voice.
+func TestBuildInternal_deniedMessageOverride(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+	t.Cleanup(func() { policystate.ResetForTesting() })
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		Restrict(&platform.Rule{Deny: []string{"config/**"}, DeniedMessage: "not part of acme cli"}).
+		MustBuild())
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	leaf := runnableUnder(t, root, "config")
+
+	err := leaf.RunE(leaf, nil)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if ve.Message != "not part of acme cli" {
+		t.Errorf("message = %q, want the integrator's DeniedMessage", ve.Message)
+	}
+}
+
+// Explicit help on a plugin-denied command must not render the original
+// usage; it answers with the same unavailable envelope.
+func TestBuildInternal_pluginDenyHelpIntercepted(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	leaf := runnableUnder(t, root, "config")
+
+	var buf bytes.Buffer
+	leaf.SetOut(&buf)
+	leaf.SetErr(&buf)
+	root.HelpFunc()(leaf, nil)
+	out := buf.String()
+	if !strings.Contains(out, "command_unavailable") {
+		t.Errorf("explicit help must answer command_unavailable, got:\n%s", out)
+	}
+	if strings.Contains(out, "Usage:") {
+		t.Errorf("explicit help must not render the original usage, got:\n%s", out)
+	}
+
+	// yaml-source presentation is untouched: a command outside the denied
+	// domain still renders normal help.
+	var normal bytes.Buffer
+	alive := findByPath(root, "skills")
+	alive.SetOut(&normal)
+	alive.SetErr(&normal)
+	root.HelpFunc()(alive, nil)
+	if strings.Contains(normal.String(), "command_unavailable") {
+		t.Errorf("non-denied command help must render normally, got:\n%s", normal.String())
+	}
+}
+
+// `lark-cli help <plugin-restricted-cmd>` must fail with the typed
+// unavailable error (exit non-zero), not print an envelope and exit 0.
+func TestBuildInternal_helpCommandReturnsUnavailable(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	helpCmd := findByPath(root, "help")
+	if helpCmd == nil || helpCmd.RunE == nil {
+		t.Fatal("custom help command not installed")
+	}
+
+	err := helpCmd.RunE(helpCmd, []string{"config"})
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("help on a restricted command must return command_unavailable, got %v", err)
+	}
+
+	// A live target renders normally and returns nil.
+	var buf bytes.Buffer
+	root.SetOut(&buf)
+	root.SetErr(&buf)
+	if err := helpCmd.RunE(helpCmd, []string{"skills"}); err != nil {
+		t.Errorf("help on a live command must succeed, got %v", err)
+	}
+}
+
+// help is a framework meta command: an allow-list rule must not deny it.
+// `help <live-cmd>` renders; `help <denied-cmd>` returns unavailable.
+func TestBuildInternal_helpSurvivesAllowList(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+	t.Cleanup(func() { policystate.ResetForTesting() })
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		Restrict(&platform.Rule{Allow: []string{"im/**"}, AllowUnannotated: true}).
+		MustBuild())
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	helpCmd := findByPath(root, "help")
+	if helpCmd == nil || helpCmd.Annotations[cmdpolicy.AnnotationDenialLayer] != "" {
+		t.Fatalf("help must not be policy-denied under an allow-list; annotations=%v", helpCmd.Annotations)
+	}
+
+	var buf bytes.Buffer
+	root.SetOut(&buf)
+	root.SetErr(&buf)
+	if err := helpCmd.RunE(helpCmd, []string{"im"}); err != nil {
+		t.Errorf("help on an allowed domain must render, got %v", err)
+	}
+
+	err := helpCmd.RunE(helpCmd, []string{"config"})
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("help on a denied domain must return command_unavailable, got %v", err)
+	}
+}
+
+// The plugin inventory surfaces the new contributions so `config plugins
+// show` can answer "what did this build customize".
+func TestBuildInternal_inventoryCoversNewCapabilities(t *testing.T) {
+	tmpHome(t)
+	withBaseSkills(t, map[string]string{"lark-a/SKILL.md": "---\ndescription: a\n---\n"})
+	restrictingPlugin(t, []string{"profile/**"}, func(b *platform.Builder) *platform.Builder {
+		return b.HideDiagnostics().
+			EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}})
+	})
+
+	buildInternal(context.Background(), buildInvocationForTest(t))
+	inv := internalplatform.GetActiveInventory()
+	if inv == nil || len(inv.Plugins) != 1 {
+		t.Fatalf("inventory = %+v, want 1 plugin", inv)
+	}
+	p := inv.Plugins[0]
+	if !p.Capabilities.HideDiagnostics {
+		t.Error("inventory must surface HideDiagnostics")
+	}
+	if p.EmbeddedSkills == nil || len(p.EmbeddedSkills.Remove) != 1 || p.EmbeddedSkills.Remove[0] != "lark-a" {
+		t.Errorf("inventory must summarise EmbeddedSkills, got %+v", p.EmbeddedSkills)
+	}
+}
+
+// Denying the whole profile domain retires --profile: hidden from help,
+// and setting it fails like an unknown flag.
+func TestBuildInternal_profileFlagGate(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"profile", "profile/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+
+	fl := root.PersistentFlags().Lookup("profile")
+	if fl == nil {
+		t.Fatal("--profile not registered")
+	}
+	if !fl.Hidden || !isPolicyGatedFlag(fl) {
+		t.Errorf("flag should be hidden and policy-gated; hidden=%v gated=%v", fl.Hidden, isPolicyGatedFlag(fl))
+	}
+
+	// Setting the flag (as cobra's parse would) must be rejected as unknown.
+	if err := root.PersistentFlags().Set("profile", "prod"); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+	err := rejectGatedFlags(root)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || !strings.Contains(ve.Message, "unknown flag") {
+		t.Errorf("setting a gated flag must fail as unknown flag, got %v", err)
+	}
+}
+
+// The gate must also fire on the real dispatch path. cobra parses a persistent
+// flag on the leaf command's merged flagset, so a gate that walks
+// root.PersistentFlags()'s changed table is a no-op once the flag is passed to
+// a subcommand. Drive root.Execute end to end and confirm the gated --profile
+// is rejected before the command body runs.
+func TestBuildInternal_profileFlagGate_RejectsOnDispatch(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"profile", "profile/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+
+	ranBody := false
+	root.AddCommand(&cobra.Command{
+		Use:  "gateprobe",
+		RunE: func(*cobra.Command, []string) error { ranBody = true; return nil },
+	})
+
+	var buf bytes.Buffer
+	root.SetOut(&buf)
+	root.SetErr(&buf)
+	root.SetArgs([]string{"--profile", "prod", "gateprobe"})
+
+	err := root.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || !strings.Contains(ve.Message, "unknown flag") {
+		t.Errorf("a gated --profile passed on the dispatch path must fail as unknown flag, got %v", err)
+	}
+	if ranBody {
+		t.Error("gated --profile must be rejected before the command body runs")
+	}
+}
+
+// Without the profile domain denied, the gate stays inert.
+func TestBuildInternal_profileFlagUntouchedWithoutDenial(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	if fl := root.PersistentFlags().Lookup("profile"); isPolicyGatedFlag(fl) {
+		t.Error("--profile must not be gated when its domain is not denied")
+	}
+}
+
+// Denying the skills domain drops the root-help skills-setup footer.
+func TestBuildInternal_skillsFooterSuppressed(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"skills", "skills/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	if strings.Contains(root.UsageTemplate(), "Skills setup") {
+		t.Error("skills-setup footer must be dropped when the skills domain is denied")
+	}
+
+	// Control: without the denial the footer stays.
+	platform.ResetForTesting()
+	policystate.ResetForTesting()
+	_, root2, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	if !strings.Contains(root2.UsageTemplate(), "Skills setup") {
+		t.Error("skills-setup footer must stay in the default build")
+	}
+}
+
+// Denying the skills command domain kills every `skills read` pointer in
+// domain help, even when the skill content itself is still embedded — the
+// command the pointers name is absent, so they would all be dead ends.
+func TestBuildInternal_skillsDomainDenyKillsHelpPointers(t *testing.T) {
+	tmpHome(t)
+	withBaseSkills(t, map[string]string{"lark-im/SKILL.md": "---\ndescription: im\n---\n"})
+	restrictingPlugin(t, []string{"skills", "skills/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+
+	im := findByPath(root, "im")
+	if im == nil {
+		t.Fatal("im domain not in tree")
+	}
+	var buf bytes.Buffer
+	im.SetOut(&buf)
+	im.SetErr(&buf)
+	root.HelpFunc()(im, nil)
+	if strings.Contains(buf.String(), "skills read") {
+		t.Errorf("domain help must not point at the denied skills command, got:\n%s", buf.String())
+	}
+}
+
+// Denying the update domain silences the _notice providers that would
+// steer the caller to `lark-cli update`.
+func TestComposePendingNotice_updateDomainDenied(t *testing.T) {
+	update.SetPending(&update.UpdateInfo{Current: "1.0.0", Latest: "1.0.1"})
+	t.Cleanup(func() { update.SetPending(nil) })
+	t.Cleanup(policystate.ResetForTesting)
+
+	policystate.SetPluginDeniedDomains(map[string]bool{"update": true})
+	if got := composePendingNotice(); got != nil {
+		t.Errorf("notices must be silenced with the update domain denied, got %+v", got)
+	}
+
+	policystate.SetPluginDeniedDomains(nil)
+	if got := composePendingNotice(); got == nil {
+		t.Error("notices must render without the denial")
+	}
+}
+
+// Default: diagnostics stay executable but leave help when their whole
+// domain is denied — cobra then drops the empty config group entirely.
+func TestBuildInternal_concealDiagnostics(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, nil)
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+
+	show := findByPath(root, "config/policy/show")
+	if show == nil {
+		t.Fatal("config policy show not in tree")
+	}
+	if !show.Hidden {
+		t.Error("exempt diagnostic should be hidden from help when its domain is denied")
+	}
+	// Still dispatchable: its RunE is the original, not an unavailable stub.
+	if show.Annotations[cmdpolicy.AnnotationDenialLayer] != "" {
+		t.Error("exempt diagnostic must not carry a denial stub by default")
+	}
+	if cfg := findByPath(root, "config"); cfg.IsAvailableCommand() {
+		t.Error("config group with no visible children must drop from help")
+	}
+}
+
+// HideDiagnostics retires the exemptions like any other denied command.
+func TestBuildInternal_hideDiagnostics(t *testing.T) {
+	tmpHome(t)
+	restrictingPlugin(t, []string{"config/**"}, func(b *platform.Builder) *platform.Builder {
+		return b.HideDiagnostics()
+	})
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+
+	show := findByPath(root, "config/policy/show")
+	if show == nil {
+		t.Fatal("config policy show not in tree")
+	}
+	err := show.RunE(show, nil)
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("hidden diagnostic must answer command_unavailable, got %v", err)
+	}
+}

cmd/prune.go

@@ -13,6 +13,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/policystate"
 )
 
 // pruneForStrictMode removes commands incompatible with the active strict mode.
@@ -105,8 +106,14 @@ func strictModeStubFrom(child *cobra.Command, mode core.StrictMode) *cobra.Comma
 		},
 		RunE: func(c *cobra.Command, _ []string) error {
 			cd := cmdpolicy.CommandDeniedFromDenial(cmdpolicy.CanonicalPath(c), denial)
+			hint := fmt.Sprintf("denied by %s policy (reason_code %s)", cd.Layer, cd.ReasonCode)
+			// The switch-policy pointer names `config strict-mode`; with
+			// the config domain plugin-denied it would be a dead end.
+			if !policystate.DomainDeniedByPlugin("config") {
+				hint += "; " + stubHint
+			}
 			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "%s", stubMessage).
-				WithHint("denied by %s policy (reason_code %s); %s", cd.Layer, cd.ReasonCode, stubHint).
+				WithHint("%s", hint).
 				WithCause(cd)
 		},
 	}

cmd/prune_test.go

@@ -14,6 +14,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 	"github.com/spf13/cobra"
 )
 
@@ -379,3 +380,41 @@ func TestStrictModeStub_PreservesOriginalMetadata(t *testing.T) {
 		t.Errorf("denial annotation overwritten or missing")
 	}
 }
+
+// The strict-mode stub's RunE appends a `config strict-mode` switch-policy
+// pointer to its hint — but only when the config domain is still present. With
+// the config domain plugin-denied that pointer is a dead end, so it is omitted;
+// the denial itself (message, subtype) is unchanged.
+func TestStrictModeStub_ConfigHintGatedByPluginDenial(t *testing.T) {
+	hintOf := func(t *testing.T) string {
+		t.Helper()
+		child := &cobra.Command{Use: "search", RunE: func(*cobra.Command, []string) error { return nil }}
+		stub := strictModeStubFrom(child, core.StrictModeBot)
+		err := stub.RunE(stub, nil)
+		var verr *errs.ValidationError
+		if !errors.As(err, &verr) {
+			t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
+		}
+		if verr.Subtype != errs.SubtypeFailedPrecondition {
+			t.Fatalf("subtype = %q, want failed_precondition", verr.Subtype)
+		}
+		return verr.Hint
+	}
+
+	t.Run("config domain present: switch-policy pointer included", func(t *testing.T) {
+		policystate.ResetForTesting()
+		t.Cleanup(policystate.ResetForTesting)
+		if h := hintOf(t); !strings.Contains(h, "config strict-mode") {
+			t.Errorf("hint = %q, want it to reference `config strict-mode`", h)
+		}
+	})
+
+	t.Run("config domain plugin-denied: switch-policy pointer omitted", func(t *testing.T) {
+		policystate.ResetForTesting()
+		t.Cleanup(policystate.ResetForTesting)
+		policystate.SetPluginDeniedDomains(map[string]bool{"config": true})
+		if h := hintOf(t); strings.Contains(h, "config strict-mode") {
+			t.Errorf("hint = %q, want no `config strict-mode` pointer when config is plugin-denied", h)
+		}
+	})
+}

cmd/root.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io/fs"
 	"os"
 	"sort"
 	"strings"
@@ -21,6 +22,7 @@ import (
 	"github.com/larksuite/cli/internal/deprecation"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/suggest"
 	"github.com/larksuite/cli/internal/update"
@@ -80,11 +82,16 @@ Global Flags:
 Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
   {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
 
-Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}{{if not .HasParent}}
-
-Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://github.com/larksuite/cli#agent-skills{{end}}
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}` + skillsSetupFooter + `
 `
 
+// skillsSetupFooter is the root-help pointer at the human one-time skills
+// setup. Split out so the presentation pass can drop it from the template
+// when an integrator plugin denies the skills domain.
+const skillsSetupFooter = `{{if not .HasParent}}
+
+Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://github.com/larksuite/cli#agent-skills{{end}}`
+
 // Execute runs the root command and returns the process exit code.
 // rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
 // UnknownFlags whitelist (installUnknownSubcommandGuard) swallows unknown flags
@@ -167,6 +174,10 @@ func setupNotices() {
 // Extracted from Execute so the composition is unit-testable.
 func composePendingNotice() map[string]interface{} {
 	notice := map[string]interface{}{}
+	// All three notices steer the caller to `lark-cli update`.
+	if policystate.DomainDeniedByPlugin("update") {
+		return nil
+	}
 	if info := update.GetPending(); info != nil {
 		notice["update"] = map[string]interface{}{
 			"current": info.Current,
@@ -658,16 +669,80 @@ func visibleFlagNames(c *cobra.Command) []string {
 	return names
 }
 
+// installHelpCommand replaces cobra's default help command so that
+// `lark-cli help <plugin-restricted-cmd>` returns a typed error (exit 2)
+// instead of printing an envelope and exiting 0 — cobra's stock help
+// command has no error channel.
+func installHelpCommand(root *cobra.Command) {
+	helpCmd := &cobra.Command{
+		Use:   "help [command]",
+		Short: "Help about any command",
+		Long:  "Help provides help for any command in the application.",
+		RunE: func(c *cobra.Command, args []string) error {
+			target, _, err := root.Find(args)
+			if err != nil || target == nil {
+				c.Printf("Unknown help topic %#q\n", args)
+				return root.Usage()
+			}
+			if msg, ok := unavailableHelpMessage(target); ok {
+				return errs.NewValidationError(errs.SubtypeCommandUnavailable, "%s", msg)
+			}
+			target.InitDefaultHelpFlag()
+			return target.Help()
+		},
+	}
+	// help attaches after policy evaluation (framework meta command, never
+	// policy-evaluated); the read annotation is defensive in case a future
+	// pass re-evaluates the finished tree.
+	cmdutil.SetRisk(helpCmd, "read")
+	cmdutil.DisableAuthCheck(helpCmd)
+	root.SetHelpCommand(helpCmd)
+	// SetHelpCommand alone defers attachment to Execute's
+	// InitDefaultHelpCmd; add it now so the built tree is complete
+	// (InitDefaultHelpCmd re-adds idempotently).
+	root.AddCommand(helpCmd)
+}
+
+// unavailableHelpMessage returns the message to render in place of help
+// for a plugin-restricted command. yaml-source denials keep original help.
+func unavailableHelpMessage(cmd *cobra.Command) (string, bool) {
+	if cmd == nil || cmd.Annotations == nil {
+		return "", false
+	}
+	if cmd.Annotations[cmdpolicy.AnnotationDenialLayer] != cmdpolicy.LayerPolicy ||
+		!cmdpolicy.IsPluginPolicySource(cmd.Annotations[cmdpolicy.AnnotationDenialSource]) {
+		return "", false
+	}
+	if msg := cmd.Annotations[cmdpolicy.AnnotationDenialMessage]; msg != "" {
+		return msg, true
+	}
+	return cmdpolicy.DefaultUnavailableMessage, true
+}
+
 // installTipsHelpFunc wraps the default help function to append a TIPS section
 // when a command has tips set via cmdutil.SetTips. It also force-shows global
 // flags that are normally hidden in single-app mode (currently --profile)
 // when rendering the root command's own help, so users discovering the CLI
 // still see them at `lark-cli --help`.
-func installTipsHelpFunc(root *cobra.Command) {
+//
+// skillContent is read lazily at help-render time (not captured up front) so
+// the domain-guide pointer reflects the resolved skill tree -- the same
+// f.SkillContent that `skills list`/`read` serve -- even though plugin skill
+// customization is applied after this help func is installed.
+func installTipsHelpFunc(root *cobra.Command, skillContent func() fs.FS) {
 	defaultHelp := root.HelpFunc()
 	root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		// Explicit help on a plugin-restricted command answers the same
+		// unavailable envelope as its RunE stub, not the original usage.
+		if msg, ok := unavailableHelpMessage(cmd); ok {
+			output.WriteTypedErrorEnvelope(cmd.ErrOrStderr(),
+				errs.NewValidationError(errs.SubtypeCommandUnavailable, "%s", msg), "")
+			return
+		}
 		if cmd == root {
-			if f := root.PersistentFlags().Lookup("profile"); f != nil && f.Hidden {
+			// Force-show flags hidden by single-app mode; never a
+			// policy-retired one.
+			if f := root.PersistentFlags().Lookup("profile"); f != nil && f.Hidden && !isPolicyGatedFlag(f) {
 				f.Hidden = false
 				defer func() { f.Hidden = true }()
 			}
@@ -675,11 +750,15 @@ func installTipsHelpFunc(root *cobra.Command) {
 		// Domain and method commands compose their agent guidance into Long lazily
 		// here (shortcuts attach after service registration); both skip the generic
 		// bottom-of-help append below.
-		if service.PrepareDomainHelp(cmd, embeddedSkillContent) {
+		if service.PrepareDomainHelp(cmd, skillContent()) {
 			defaultHelp(cmd, args)
 			return
 		}
-		if service.PrepareMethodHelp(cmd) {
+		if service.PrepareMethodHelp(cmd, skillContent()) {
+			defaultHelp(cmd, args)
+			return
+		}
+		if service.PrepareShortcutHelp(cmd, skillContent()) {
 			defaultHelp(cmd, args)
 			return
 		}

cmd/root_risk_help_test.go

@@ -5,6 +5,7 @@ package cmd
 
 import (
 	"bytes"
+	"io/fs"
 	"strings"
 	"testing"
 
@@ -12,6 +13,10 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// nilSkills is the skill-content getter used by help-func tests that do
+// not exercise the domain-guide pointer.
+func nilSkills() fs.FS { return nil }
+
 // rendersHelp runs the wrapped help func and returns stdout.
 func rendersHelp(t *testing.T, cmd *cobra.Command) string {
 	t.Helper()
@@ -24,7 +29,7 @@ func rendersHelp(t *testing.T, cmd *cobra.Command) string {
 
 func TestHelpFunc_RendersRiskLineWhenAnnotated(t *testing.T) {
 	root := &cobra.Command{Use: "lark-cli"}
-	installTipsHelpFunc(root)
+	installTipsHelpFunc(root, nilSkills)
 
 	child := &cobra.Command{Use: "delete", Short: "delete a file"}
 	cmdutil.SetRisk(child, "high-risk-write")
@@ -38,7 +43,7 @@ func TestHelpFunc_RendersRiskLineWhenAnnotated(t *testing.T) {
 
 func TestHelpFunc_NoRiskLineWhenUnannotated(t *testing.T) {
 	root := &cobra.Command{Use: "lark-cli"}
-	installTipsHelpFunc(root)
+	installTipsHelpFunc(root, nilSkills)
 
 	child := &cobra.Command{Use: "list", Short: "list items"}
 	root.AddCommand(child)
@@ -51,7 +56,7 @@ func TestHelpFunc_NoRiskLineWhenUnannotated(t *testing.T) {
 
 func TestHelpFunc_RiskLinePrecedesTips(t *testing.T) {
 	root := &cobra.Command{Use: "lark-cli"}
-	installTipsHelpFunc(root)
+	installTipsHelpFunc(root, nilSkills)
 
 	child := &cobra.Command{Use: "delete", Short: "delete a file"}
 	cmdutil.SetRisk(child, "high-risk-write")

cmd/service/affordance.go

@@ -71,11 +71,18 @@ func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 }
 
 // domainHelpBase returns the description to seed domain help with — the
-// hand-authored Long when present, else the Short — captured once into an
-// annotation so re-rendering reuses the pristine text instead of the
-// already-augmented Long.
+// hand-authored Long when present, else the Short.
 func domainHelpBase(cmd *cobra.Command) string {
-	if base, ok := cmd.Annotations[domainBaseAnnotation]; ok {
+	return captureHelpBase(cmd, domainBaseAnnotation)
+}
+
+// captureHelpBase records a command's pristine lead text once — its
+// hand-authored Long, or Short when Long is empty — into the given annotation,
+// so lazy re-renders compose onto the original text instead of onto an
+// already-augmented Long. This is what lets a shortcut's PostMount-authored
+// Long survive: it becomes the base the affordance block is appended below.
+func captureHelpBase(cmd *cobra.Command, key string) string {
+	if base, ok := cmd.Annotations[key]; ok {
 		return base
 	}
 	base := cmd.Long
@@ -85,7 +92,7 @@ func domainHelpBase(cmd *cobra.Command) string {
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	cmd.Annotations[domainBaseAnnotation] = base
+	cmd.Annotations[key] = base
 	return base
 }
 
@@ -101,12 +108,12 @@ func methodLong(description, schemaPath, paramsOnly string) string {
 }
 
 // Annotation keys PrepareMethodHelp reads to rebuild a method command's Long.
+// The affordance overlay coordinates live in cmdmeta (shared with shortcuts).
 const (
-	affordanceServiceAnnotation = "affordance-service"
-	affordanceMethodAnnotation  = "affordance-method"
-	schemaPathAnnotation        = "method-schema-path"
-	paramsOnlyAnnotation        = "method-params-only"
-	domainBaseAnnotation        = "affordance-domain-base"
+	schemaPathAnnotation   = "method-schema-path"
+	paramsOnlyAnnotation   = "method-params-only"
+	domainBaseAnnotation   = "affordance-domain-base"
+	shortcutBaseAnnotation = "affordance-shortcut-base"
 )
 
 // setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
@@ -115,10 +122,7 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	if service != "" && methodID != "" {
-		cmd.Annotations[affordanceServiceAnnotation] = service
-		cmd.Annotations[affordanceMethodAnnotation] = methodID
-	}
+	cmdmeta.SetAffordanceRef(cmd, service, methodID)
 	cmd.Annotations[schemaPathAnnotation] = schemaPath
 	if paramsOnly != "" {
 		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
@@ -128,8 +132,11 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 // PrepareMethodHelp rebuilds a generated method command's Long with the agent
 // guidance at the TOP (Risk, then the affordance block, then the schema
 // pointer), returning false for non-method commands. The overlay is parsed
-// here — only when help is rendered.
-func PrepareMethodHelp(cmd *cobra.Command) bool {
+// here — only when help is rendered. skillFS (nil-safe) gates the related-skill
+// pointers: each is emitted only when it resolves in the skill tree (see
+// affordance.SkillStatPath), so a typo or a build without embedded skills never
+// prints a `skills read` that cannot be opened.
+func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 	ann := cmd.Annotations
 	if ann == nil {
 		return false
@@ -141,22 +148,15 @@ func PrepareMethodHelp(cmd *cobra.Command) bool {
 
 	var b strings.Builder
 	b.WriteString(cmd.Short)
-	if level, ok := cmdutil.GetRisk(cmd); ok {
-		// --yes asserts the USER confirmed; the agent must not self-approve.
-		if level == cmdutil.RiskHighRiskWrite {
-			fmt.Fprintf(&b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
-		} else {
-			fmt.Fprintf(&b, "\n\nRisk: %s", level)
-		}
-	}
+	writeRisk(&b, cmd)
 
 	var skills []string
 	if raw, ok := affordanceRaw(cmd); ok {
-		if block := renderAffordance(meta.Method{Affordance: raw}); block != "" {
-			b.WriteString("\n\n")
-			b.WriteString(block)
-		}
 		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
+			if block := renderAffordanceValue(a); block != "" {
+				b.WriteString("\n\n")
+				b.WriteString(block)
+			}
 			skills = a.Skills
 		}
 	}
@@ -164,17 +164,95 @@ func PrepareMethodHelp(cmd *cobra.Command) bool {
 	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(ann[paramsOnlyAnnotation])
 
-	if len(skills) > 0 {
-		b.WriteString("\n\nWorkflow skill (end-to-end usage):")
-		for _, s := range skills {
-			fmt.Fprintf(&b, "\n  lark-cli skills read %s", s)
-		}
-	}
+	writeRelatedSkills(&b, skills, skillFS)
 
 	cmd.Long = b.String()
 	return true
 }
 
+// PrepareShortcutHelp composes a +-prefixed shortcut's Long from its affordance
+// overlay — the same top layout as method help (description, Risk, guidance
+// block, related skills) minus the schema pointer, which shortcuts have none
+// of. Returns false when the command is not a shortcut or carries no overlay
+// entry, so shortcuts without guidance keep the default help plus the bottom
+// risk/tips append.
+//
+// The lead is the command's pristine base (captureHelpBase): a shortcut that
+// set a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST
+// read the skill" directive) keeps it — the affordance block is appended below,
+// never clobbering it.
+//
+// Tips precedence (intentional, not a bug): the overlay's ### Tips win. The
+// shortcut's declarative Tips (the Go Tips field) are only a fallback used when
+// the overlay declares none; when the overlay has tips, the Go tips are dropped
+// (replaced, not merged) so tips never render twice. Authoring a ### Tips block
+// therefore silently retires that shortcut's Go Tips — consolidate into one.
+func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
+	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceShortcut {
+		return false
+	}
+	raw, ok := affordanceRaw(cmd)
+	if !ok {
+		return false
+	}
+	a, ok := (meta.Method{Affordance: raw}).ParsedAffordance()
+	if !ok {
+		return false
+	}
+	if len(a.Tips) == 0 {
+		a.Tips = cmdutil.GetTips(cmd)
+	}
+
+	var b strings.Builder
+	b.WriteString(captureHelpBase(cmd, shortcutBaseAnnotation))
+	writeRisk(&b, cmd)
+	if block := renderAffordanceValue(a); block != "" {
+		b.WriteString("\n\n")
+		b.WriteString(block)
+	}
+	writeRelatedSkills(&b, a.Skills, skillFS)
+
+	cmd.Long = b.String()
+	return true
+}
+
+// writeRisk appends the "Risk: <level>" line, warning agents not to self-approve
+// high-risk-write commands. A no-op when the command has no risk annotation.
+func writeRisk(b *strings.Builder, cmd *cobra.Command) {
+	level, ok := cmdutil.GetRisk(cmd)
+	if !ok {
+		return
+	}
+	// --yes asserts the USER confirmed; the agent must not self-approve.
+	if level == cmdutil.RiskHighRiskWrite {
+		fmt.Fprintf(b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
+	} else {
+		fmt.Fprintf(b, "\n\nRisk: %s", level)
+	}
+}
+
+// writeRelatedSkills appends the "Related skills" block for the entries that
+// exist in skillFS. Nothing is written when skillFS is nil or no entry resolves,
+// so help never prints a `skills read` pointer that cannot be opened.
+func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS) {
+	if skillFS == nil || len(skills) == 0 {
+		return
+	}
+	var avail []string
+	for _, s := range skills {
+		if _, err := fs.Stat(skillFS, affordance.SkillStatPath(s)); err == nil {
+			avail = append(avail, s)
+		}
+	}
+	if len(avail) == 0 {
+		return
+	}
+	b.WriteString("\n\nRelated skills (read for end-to-end usage):")
+	for _, s := range avail {
+		fmt.Fprintf(b, "\n  lark-cli skills read %s", s)
+	}
+}
+
 // affordanceLookup is the overlay source; a package var so tests can inject.
 var affordanceLookup = affordance.For
 
@@ -189,12 +267,8 @@ func RenderAffordanceForCmd(cmd *cobra.Command) string {
 }
 
 func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
-	if cmd.Annotations == nil {
-		return nil, false
-	}
-	service := cmd.Annotations[affordanceServiceAnnotation]
-	methodID := cmd.Annotations[affordanceMethodAnnotation]
-	if service == "" || methodID == "" {
+	service, methodID, ok := cmdmeta.AffordanceRef(cmd)
+	if !ok {
 		return nil, false
 	}
 	return affordanceLookup(service, methodID)
@@ -207,7 +281,13 @@ func renderAffordance(m meta.Method) string {
 	if !ok {
 		return ""
 	}
+	return renderAffordanceValue(a)
+}
 
+// renderAffordanceValue renders an already-parsed affordance. Split from
+// renderAffordance so callers can render a value they have adjusted first (e.g.
+// a shortcut folding its declarative tips into an overlay that has none).
+func renderAffordanceValue(a meta.Affordance) string {
 	var sections []string
 	bullets := func(title string, items []string) {
 		var nonEmpty []string

cmd/service/affordance_test.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"strings"
 	"testing"
+	"testing/fstest"
 
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -70,8 +71,8 @@ func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
 		t.Errorf("affordance must not be baked into Long (lazy):\n%s", cmd.Long)
 	}
 	// The lookup ref is recorded so the help path can resolve it later.
-	if cmd.Annotations[affordanceServiceAnnotation] != "im" || cmd.Annotations[affordanceMethodAnnotation] != "messages.create" {
-		t.Errorf("affordance ref annotations = %v, want im/messages.create", cmd.Annotations)
+	if svc, method, ok := cmdmeta.AffordanceRef(cmd); !ok || svc != "im" || method != "messages.create" {
+		t.Errorf("affordance ref = %q/%q (ok=%v), want im/messages.create", svc, method, ok)
 	}
 }
 
@@ -119,7 +120,7 @@ func TestPrepareMethodHelp(t *testing.T) {
 	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
 	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
 
-	if !PrepareMethodHelp(cmd) {
+	if !PrepareMethodHelp(cmd, nil) {
 		t.Fatal("PrepareMethodHelp returned false for a service-method command")
 	}
 	long := cmd.Long
@@ -136,11 +137,133 @@ func TestPrepareMethodHelp(t *testing.T) {
 	}
 
 	// A non-service command (no schema-path annotation) is left untouched.
-	if PrepareMethodHelp(&cobra.Command{Use: "plain"}) {
+	if PrepareMethodHelp(&cobra.Command{Use: "plain"}, nil) {
 		t.Error("PrepareMethodHelp should return false for a non-service command")
 	}
 }
 
+// PrepareShortcutHelp composes a shortcut's Long from its overlay with the same
+// top layout as method help (no schema pointer), folding declarative tips when
+// the overlay declares none, and leaves shortcuts without an overlay entry (and
+// non-shortcut commands) for the default help path.
+func TestPrepareShortcutHelp(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
+		if service == "calendar" && methodID == "+create" {
+			return json.RawMessage(`{"use_when":["高层创建日程"],"skills":["lark-calendar"]}`), true
+		}
+		return nil, false
+	}
+
+	sc := &cobra.Command{Use: "+create", Short: "Create an event"}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
+	cmdutil.SetRisk(sc, "write")
+	cmdutil.SetTips(sc, []string{"start/end 收 ISO 8601"})
+
+	if !PrepareShortcutHelp(sc, nil) {
+		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
+	}
+	for _, want := range []string{"Create an event", "Risk: write", "When to use:", "高层创建日程", "Tips:", "start/end 收 ISO 8601"} {
+		if !strings.Contains(sc.Long, want) {
+			t.Errorf("shortcut Long missing %q:\n%s", want, sc.Long)
+		}
+	}
+	if strings.Contains(sc.Long, "Full parameter schema:") {
+		t.Errorf("shortcut Long must not carry a schema pointer:\n%s", sc.Long)
+	}
+
+	// No overlay entry -> leave it for the default help path.
+	bare := &cobra.Command{Use: "+bare", Short: "x"}
+	cmdmeta.SetSource(bare, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(bare, "calendar", "+bare")
+	if PrepareShortcutHelp(bare, nil) {
+		t.Error("PrepareShortcutHelp should return false when the shortcut has no overlay")
+	}
+
+	// Non-shortcut source is ignored even with a ref.
+	notSc := &cobra.Command{Use: "create", Short: "x"}
+	cmdmeta.SetAffordanceRef(notSc, "calendar", "+create")
+	if PrepareShortcutHelp(notSc, nil) {
+		t.Error("PrepareShortcutHelp should return false for a non-shortcut command")
+	}
+}
+
+// Related-skill pointers are gated on existence: a skill that resolves in the
+// skill FS renders, a typo is dropped (never print an unopenable `skills read`),
+// and a nil skill FS suppresses the whole block.
+func TestRelatedSkillsStatGating(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["x"],"skills":["lark-real","lark-typo","lark-real/references/deep.md","lark-real/references/missing.md"]}`), true
+	}
+	skillFS := fstest.MapFS{
+		"lark-real/SKILL.md":           {Data: []byte("# real")},
+		"lark-real/references/deep.md": {Data: []byte("# deep")},
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "d"}
+
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
+	if !PrepareMethodHelp(cmd, skillFS) {
+		t.Fatal("PrepareMethodHelp returned false")
+	}
+	if !strings.Contains(cmd.Long, "skills read lark-real\n") {
+		t.Errorf("existing bare-name skill should render on its own line; got:\n%s", cmd.Long)
+	}
+	if strings.Contains(cmd.Long, "lark-typo") {
+		t.Errorf("nonexistent skill must be dropped, not printed as an unopenable pointer; got:\n%s", cmd.Long)
+	}
+	// A name/relpath reference to an existing file renders; a missing one drops.
+	if !strings.Contains(cmd.Long, "skills read lark-real/references/deep.md") {
+		t.Errorf("existing reference entry should render; got:\n%s", cmd.Long)
+	}
+	if strings.Contains(cmd.Long, "references/missing.md") {
+		t.Errorf("nonexistent reference must be dropped; got:\n%s", cmd.Long)
+	}
+
+	// nil skill FS: the whole Related-skills block is suppressed.
+	bare := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
+	PrepareMethodHelp(bare, nil)
+	if strings.Contains(bare.Long, "Related skills") {
+		t.Errorf("nil skillFS should suppress the skills block; got:\n%s", bare.Long)
+	}
+}
+
+// A shortcut that set a hand-authored Long (as the docs shortcuts do in
+// PostMount) keeps it as the lead: the affordance block is appended below, not
+// clobbered, and re-rendering does not double-append.
+func TestPrepareShortcutHelp_PreservesPostMountLong(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["高层创建日程"]}`), true
+	}
+
+	const authored = "Custom docs help. AI agents MUST read the skill first."
+	sc := &cobra.Command{Use: "+create", Short: "Create", Long: authored}
+	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
+
+	if !PrepareShortcutHelp(sc, nil) {
+		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
+	}
+	if !strings.HasPrefix(sc.Long, authored) {
+		t.Errorf("hand-authored Long must lead, not be clobbered; got:\n%s", sc.Long)
+	}
+	if !strings.Contains(sc.Long, "When to use:") {
+		t.Errorf("affordance block should be appended below the base; got:\n%s", sc.Long)
+	}
+	// Re-render must reuse the captured base, not append the block twice.
+	PrepareShortcutHelp(sc, nil)
+	if n := strings.Count(sc.Long, "When to use:"); n != 1 {
+		t.Errorf("affordance appended %d times across re-renders, want 1:\n%s", n, sc.Long)
+	}
+}
+
 // domainCmd wires a domain-tagged command with a subcommand under a root, the
 // shape PrepareDomainHelp expects.
 func domainCmd(short, long string) *cobra.Command {
@@ -174,6 +297,26 @@ func TestPrepareDomainHelp_PreservesHandAuthoredLong(t *testing.T) {
 }
 
 // A service domain carries only a Short at help time; it seeds the base.
+// The domain-guide pointer is likewise gated: removing the domain's skill
+// drops the pointer instead of leaving it dangling.
+func TestPrepareDomainHelp_GatesGuidePointerOnFS(t *testing.T) {
+	present := domainCmd("Consume and manage real-time events", "")
+	if !PrepareDomainHelp(present, fstest.MapFS{"lark-event/SKILL.md": &fstest.MapFile{Data: []byte("x")}}) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if !strings.Contains(present.Long, "lark-cli skills read lark-event") {
+		t.Errorf("skill present should emit the domain-guide pointer; got:\n%s", present.Long)
+	}
+
+	removed := domainCmd("Consume and manage real-time events", "")
+	if !PrepareDomainHelp(removed, fstest.MapFS{}) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if strings.Contains(removed.Long, "skills read lark-event") {
+		t.Errorf("removed skill must leave no domain-guide pointer; got:\n%s", removed.Long)
+	}
+}
+
 func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
 	dom := domainCmd("Message and group chat management", "")
 	if !PrepareDomainHelp(dom, nil) {

cmd/service/service_test.go

@@ -4,10 +4,14 @@
 package service
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
+	"mime"
+	"mime/multipart"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -1132,6 +1136,63 @@ func TestDetectFileFields(t *testing.T) {
 	}
 }
 
+// parseMultipartFilenames drives one service-method --file upload through the
+// mock transport and returns a map of field name -> part filename parsed from
+// the captured multipart body. Mirrors cmd/api's helper of the same name
+// (inlined here rather than shared, since the two live in different packages)
+// to give BuildFormdata's shared local-file fix a second real entry-point
+// covering it.
+func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) map[string]string {
+	t.Helper()
+	ct := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(ct)
+	if err != nil {
+		t.Fatalf("parse Content-Type %q: %v", ct, err)
+	}
+	if !strings.HasPrefix(mediaType, "multipart/") {
+		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
+	}
+	filenames := map[string]string{}
+	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	for {
+		part, err := mr.NextPart()
+		if err != nil {
+			break
+		}
+		if fn := part.FileName(); fn != "" {
+			filenames[part.FormName()] = fn
+		}
+	}
+	return filenames
+}
+
+func TestServiceMethod_FileUpload_PreservesFilename(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, testConfig)
+
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile(filepath.Join(dir, "photo.jpg"), []byte("fake-image"), 0600); err != nil {
+		t.Fatalf("write test file: %v", err)
+	}
+
+	stub := &httpmock.Stub{
+		URL:  "/open-apis/im/v1/images",
+		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"image_key": "img_xxx"}},
+	}
+	reg.Register(stub)
+
+	cmd := NewCmdServiceMethod(f, imSpec(), imImageMethod(), "create", "images", nil)
+	cmd.SetArgs([]string{"--file", "photo.jpg", "--data", `{"image_type":"message"}`, "--as", "bot"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	filenames := parseMultipartFilenames(t, stub)
+	if got := filenames["image"]; got != "photo.jpg" {
+		t.Fatalf("part filename for field %q = %q, want %q", "image", got, "photo.jpg")
+	}
+}
+
 func TestServiceMethod_JsonFlag_Accepted(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 

cmd/skill_customization_test.go

@@ -0,0 +1,227 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/platform"
+	"github.com/larksuite/cli/internal/policystate"
+	"github.com/larksuite/cli/internal/skillcontent"
+)
+
+// withBaseSkills swaps the process-global embedded skill tree for the
+// duration of a test, restoring it afterward.
+func withBaseSkills(t *testing.T, files map[string]string) {
+	t.Helper()
+	base := fstest.MapFS{}
+	for p, content := range files {
+		base[p] = &fstest.MapFile{Data: []byte(content)}
+	}
+	saved := embeddedSkillContent
+	t.Cleanup(func() { embeddedSkillContent = saved })
+	embeddedSkillContent = base
+}
+
+// A plugin's SkillsOverlay must reshape the tree the factory serves: skills
+// list/read read f.SkillContent, so a resolved removal/overlay shows up here.
+// (The --help pointers are gated on the same f.SkillContent; that gating is
+// covered by the PrepareDomainHelp/PrepareMethodHelp tests in cmd/service.)
+func TestBuildInternal_appliesPluginSkillsOverlay(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+
+	withBaseSkills(t, map[string]string{
+		"lark-a/SKILL.md":      "---\ndescription: a\n---\n",
+		"lark-b/SKILL.md":      "---\ndescription: b\n---\n",
+		"lark-shared/SKILL.md": "---\ndescription: shared\n---\n",
+	})
+
+	overlay := fstest.MapFS{
+		"lark-new/SKILL.md": &fstest.MapFile{Data: []byte("---\ndescription: new\n---\n")},
+	}
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{
+			Remove:  []string{"lark-shared"},
+			Overlay: overlay,
+		}).MustBuild())
+
+	f, _, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	if f.SkillContent == nil {
+		t.Fatal("f.SkillContent is nil after skill resolution")
+	}
+
+	skills, err := skillcontent.New(f.SkillContent).List()
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	var names []string
+	for _, s := range skills {
+		names = append(names, s.Name)
+	}
+	if got := strings.Join(names, ","); got != "lark-a,lark-b,lark-new" {
+		t.Errorf("skills = %q, want lark-a,lark-b,lark-new (shared removed, new added)", got)
+	}
+}
+
+// Two plugins each customizing skills must abort at dispatch with a
+// structured envelope carrying reason_code multiple_skills_overlay_plugins, not
+// silently fall back to the default tree.
+func TestBuildInternal_multipleSkillPluginsGuard(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+
+	withBaseSkills(t, map[string]string{"lark-a/SKILL.md": "---\ndescription: a\n---\n"})
+
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}).MustBuild())
+	platform.Register(platform.NewPlugin("globex", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}).MustBuild())
+
+	_, root, reg := buildInternal(context.Background(), buildInvocationForTest(t))
+	if reg != nil {
+		t.Errorf("skill conflict guard path should yield nil registry")
+	}
+
+	leaf := findRunnableLeaf(root)
+	if leaf == nil {
+		t.Fatal("no runnable leaf in command tree")
+	}
+	err := leaf.RunE(leaf, nil)
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T %+v", err, err)
+	}
+	if verr.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("subtype = %q, want failed_precondition", verr.Subtype)
+	}
+	if !strings.Contains(verr.Hint, "multiple_skills_overlay_plugins") {
+		t.Errorf("hint should surface reason_code multiple_skills_overlay_plugins, got %q", verr.Hint)
+	}
+}
+
+// Allow keeps only the listed skills from the base — a CLI upgrade adding
+// new embedded skills cannot widen an allow-listed build.
+func TestBuildInternal_appliesAllowList(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+	t.Cleanup(func() { policystate.ResetForTesting() })
+
+	withBaseSkills(t, map[string]string{
+		"lark-a/SKILL.md": "---\ndescription: a\n---\n",
+		"lark-b/SKILL.md": "---\ndescription: b\n---\n",
+		"lark-c/SKILL.md": "---\ndescription: c\n---\n",
+	})
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{Allow: []string{"lark-a", "lark-c"}}).
+		MustBuild())
+
+	f, _, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	skills, err := skillcontent.New(f.SkillContent).List()
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	var names []string
+	for _, s := range skills {
+		names = append(names, s.Name)
+	}
+	if got := strings.Join(names, ","); got != "lark-a,lark-c" {
+		t.Errorf("skills = %q, want lark-a,lark-c (allow-list)", got)
+	}
+}
+
+// A plugin whose SkillsOverlay cannot compose (Remove naming a skill absent
+// from the base) must abort with reason_code invalid_skills_overlay.
+func TestBuildInternal_invalidSkillsOverlayGuard(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+
+	withBaseSkills(t, map[string]string{"lark-a/SKILL.md": "---\ndescription: a\n---\n"})
+
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-does-not-exist"}}).MustBuild())
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
+	leaf := findRunnableLeaf(root)
+	if leaf == nil {
+		t.Fatal("no runnable leaf in command tree")
+	}
+	err := leaf.RunE(leaf, nil)
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T %+v", err, err)
+	}
+	if verr.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("subtype = %q, want failed_precondition", verr.Subtype)
+	}
+	if !strings.Contains(verr.Hint, "invalid_skills_overlay") {
+		t.Errorf("hint should surface reason_code invalid_skills_overlay, got %q", verr.Hint)
+	}
+}
+
+// WithEmbeddedSkills customizes skills for a caller that builds the tree directly
+// (no plugin) — the build-option analogue of a plugin's EmbeddedSkills(...).
+func TestBuildInternal_withSkillsOption(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+
+	withBaseSkills(t, map[string]string{
+		"lark-a/SKILL.md":      "---\ndescription: a\n---\n",
+		"lark-shared/SKILL.md": "---\ndescription: shared\n---\n",
+	})
+
+	f, _, _ := buildInternal(context.Background(), buildInvocationForTest(t),
+		WithEmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-shared"}}))
+	skills, err := skillcontent.New(f.SkillContent).List()
+	if err != nil {
+		t.Fatalf("List: %v", err)
+	}
+	var names []string
+	for _, s := range skills {
+		names = append(names, s.Name)
+	}
+	if got := strings.Join(names, ","); got != "lark-a" {
+		t.Errorf("skills = %q, want lark-a (shared removed via WithEmbeddedSkills)", got)
+	}
+}
+
+// WithEmbeddedSkills and a plugin's EmbeddedSkills() are two owners of skill content; the
+// single-owner rule aborts startup.
+func TestBuildInternal_withSkillsPlusPluginConflicts(t *testing.T) {
+	tmpHome(t)
+	platform.ResetForTesting()
+	t.Cleanup(platform.ResetForTesting)
+
+	withBaseSkills(t, map[string]string{"lark-a/SKILL.md": "---\ndescription: a\n---\n"})
+	platform.Register(platform.NewPlugin("acme", "1.0").
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}).MustBuild())
+
+	_, root, _ := buildInternal(context.Background(), buildInvocationForTest(t),
+		WithEmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}))
+	leaf := findRunnableLeaf(root)
+	if leaf == nil {
+		t.Fatal("no runnable leaf in command tree")
+	}
+	err := leaf.RunE(leaf, nil)
+	var verr *errs.ValidationError
+	if !errors.As(err, &verr) {
+		t.Fatalf("expected *errs.ValidationError, got %T %+v", err, err)
+	}
+	if verr.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("subtype = %q, want failed_precondition", verr.Subtype)
+	}
+	if !strings.Contains(verr.Hint, "multiple_skills_overlay_plugins") {
+		t.Errorf("WithEmbeddedSkills + plugin should conflict; hint = %q", verr.Hint)
+	}
+}

errs/subtypes.go

@@ -14,6 +14,7 @@ const (
 const (
 	SubtypeInvalidArgument    Subtype = "invalid_argument"    // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
 	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
+	SubtypeCommandUnavailable Subtype = "command_unavailable" // command not included in this build (integrator-restricted distribution); absent, not gated
 )
 
 // CategoryAuthentication subtypes

extension/platform/README.md

@@ -60,6 +60,7 @@ You should see `audit` in the plugin list.
 | `Wrap`                     | Around each command's RunE         | Yes (return `*AbortError`)       |
 | `On(Startup/Shutdown)`     | Process lifecycle                  | N/A                              |
 | `Restrict(Rule)`           | Bootstrap-time, ≥1 per plugin      | Denies whole subtrees            |
+| `EmbeddedSkills(SkillsOverlay)`        | Bootstrap-time, ≤1 per plugin      | No (customizes embedded skills)  |
 
 ### Plugin lifecycle
 
@@ -79,7 +80,7 @@ sequenceDiagram
     Host->>SDK: InstallAll()
     SDK->>Plugin: Capabilities()
     SDK->>Plugin: Install(Registrar)
-    Plugin->>SDK: Observe / Wrap / Restrict / On(Startup,Shutdown)
+    Plugin->>SDK: Observe / Wrap / Restrict / EmbeddedSkills / On(Startup,Shutdown)
     SDK->>Plugin: On(Startup) fire
 
     Note over Host,Plugin: Each command dispatch
@@ -113,6 +114,35 @@ the rejected dispatch.
   widen another's policy). YAML policy at `~/.lark-cli/policy.yml` (which
   may itself list several rules under `rules:`) is shadowed by any plugin
   Restrict.
+- A plugin may call `EmbeddedSkills()` at most once to customize the embedded
+  skill tree — `Allow` keeps only the listed skills (the allow-list
+  counterpart of `Rule.Allow`, so a CLI upgrade cannot widen the build;
+  `Remove` wins over `Allow`, and `Overlay` entries are exempt), `Remove`
+  drops skills, `Overlay` adds/replaces ones, or swap the whole `Base` —
+  layered over the CLI default. Unlike `Restrict()`
+  it is NOT a security boundary and does not imply `FailClosed`: it
+  shapes fail-open guidance content. Removing a skill only drops its
+  `skills read` / `--help` guidance — it does NOT disable the matching
+  commands (use `Restrict()` for that). Only ONE plugin per binary may
+  contribute a `SkillsOverlay`; two DISTINCT plugins is a deliberate
+  `multiple_skills_overlay_plugins` error.
+- A command denied by a **plugin** Rule presents as absent, not as
+  forbidden: it leaves `--help` and completion, explicit help on it is
+  intercepted, and invoking it answers `subtype=command_unavailable`
+  with no policy vocabulary and no recovery hint. Set
+  `Rule.DeniedMessage` to replace the default
+  "command not included in this build" with your product's own wording.
+  yaml-source denials keep the classic `command_denied` presentation —
+  the user owns that policy and needs to see how to adjust it. Denying a
+  whole domain also retires what points at it: `--profile` (profile
+  domain) hides and rejects use, the root-help skills footer (skills),
+  update notices (update), and the `auth login` recovery hint (auth)
+  stop rendering.
+- `config policy show` / `config plugins show` stay executable under any
+  plugin policy (hidden from help when their domain is denied) so an
+  operator can still inspect the rule that locked the build. An
+  integrator shipping a fully-managed distribution opts out with
+  `HideDiagnostics()` — requires `Restrict()` on the same plugin.
 - The `Wrap` factory runs **once per command dispatch**, not at
   install time. Long-lived state (clients, caches, metrics counters)
   must live on the Plugin struct or in package-level variables.
@@ -153,6 +183,8 @@ messages are localised and may change between releases.
 | `invalid_hook_registration` | Hook factory returns nil / Wrap chain re-entry / etc.                          | Yes                    |
 | `invalid_rule`              | Rule fails ValidateRule (malformed glob, bad MaxRisk, unknown Identity)        | Yes                    |
 | `multiple_restrict_plugins` | Two or more DISTINCT plugins each contributed Restrict (one plugin may contribute several rules) | Yes  |
+| `invalid_skills_overlay`        | Staging fault (`EmbeddedSkills(nil)` / second call in one plugin) honours FailurePolicy; a `SkillsOverlay` that can't compose (`Remove` names a skill absent from the base, `Overlay` entry lacks `SKILL.md`) always aborts via a fatal dispatch guard | Mixed — see left |
+| `multiple_skills_overlay_plugins` | Two or more DISTINCT plugins each contributed a `SkillsOverlay` (only one may own skill content)  | No — always aborts (dispatch guard) |
 | `install_failed`            | `Plugin.Install` returned a non-nil error                                      | Yes                    |
 | `install_panic`             | `Plugin.Install` panicked                                                      | Yes                    |
 
@@ -187,8 +219,8 @@ should additionally check `detail.layer == "policy"`.
 - [Runnable example: audit observer](./examples/audit-observer/)
 - [Runnable example: read-only policy](./examples/readonly-policy/)
 - Builder API: see [`builder.go`](./builder.go) for the full DSL
-  (`NewPlugin`, `Observer`, `Wrap`, `Restrict`, `FailOpen`/`FailClosed`,
-  `MustBuild`).
+  (`NewPlugin`, `Observer`, `Wrap`, `Restrict`, `EmbeddedSkills`,
+  `HideDiagnostics`, `FailOpen`/`FailClosed`, `MustBuild`).
 - Inventory diagnostic: run `lark-cli config plugins show` after
   installing your plugin to see hooks/rules attributed to your plugin
   name.

extension/platform/builder.go

@@ -36,8 +36,9 @@ type Builder struct {
 	version string
 	caps    Capabilities
 
-	actions []func(Registrar)
-	rules   []*Rule
+	actions       []func(Registrar)
+	rules         []*Rule
+	skillsOverlay *SkillsOverlay
 
 	hookNames map[string]bool
 	errs      []error
@@ -81,6 +82,15 @@ func (b *Builder) FailClosed() *Builder {
 	return b
 }
 
+// HideDiagnostics retires the policy self-inspection commands
+// (`config policy show`, `config plugins show`), which otherwise stay
+// executable under a plugin policy as the operator's escape hatch.
+// Requires Restrict() on the same plugin; Build fails otherwise.
+func (b *Builder) HideDiagnostics() *Builder {
+	b.caps.HideDiagnostics = true
+	return b
+}
+
 // Observer registers an Observer. Multiple calls accumulate.
 func (b *Builder) Observer(when When, hookName string, sel Selector, fn Observer) *Builder {
 	if !b.validateHookName(hookName, "observer") {
@@ -145,6 +155,35 @@ func (b *Builder) Restrict(rule *Rule) *Builder {
 	return b
 }
 
+// EmbeddedSkills contributes a SkillsOverlay (see SkillsOverlay)
+// customizing the CLI's embedded skill content. Unlike Restrict it does
+// NOT imply FailClosed: skill customization is guidance content, not a
+// security boundary. A plugin owns at most one SkillsOverlay, so calling
+// EmbeddedSkills more than once is a build error.
+func (b *Builder) EmbeddedSkills(spec *SkillsOverlay) *Builder {
+	if spec == nil {
+		b.errs = append(b.errs, errors.New("EmbeddedSkills(nil): spec must not be nil"))
+		return b
+	}
+	if b.skillsOverlay != nil {
+		b.errs = append(b.errs, errors.New("EmbeddedSkills() called more than once; a plugin owns at most one SkillsOverlay"))
+		return b
+	}
+	b.skillsOverlay = cloneSkillsOverlay(spec)
+	return b
+}
+
+// cloneSkillsOverlay snapshots the caller's spec so a later mutation of the
+// same *SkillsOverlay cannot alter the staged copy. The Remove slice is
+// copied; Overlay/Base are fs.FS handles retained by reference (an fs.FS
+// is a read-only view, not caller-mutable state).
+func cloneSkillsOverlay(spec *SkillsOverlay) *SkillsOverlay {
+	cp := *spec
+	cp.Allow = append([]string(nil), spec.Allow...)
+	cp.Remove = append([]string(nil), spec.Remove...)
+	return &cp
+}
+
 // Build returns the configured Plugin, or an error if any builder
 // step found a fault. MustBuild panics on the same error.
 //
@@ -155,15 +194,20 @@ func (b *Builder) Build() (Plugin, error) {
 		b.errs = append(b.errs, errors.New(
 			"Restrict() requires FailClosed; do not call FailOpen() after Restrict()"))
 	}
+	if b.caps.HideDiagnostics && len(b.rules) == 0 {
+		b.errs = append(b.errs, errors.New(
+			"HideDiagnostics() requires Restrict(): there is no integrator policy to hide"))
+	}
 	if len(b.errs) > 0 {
 		return nil, errors.Join(b.errs...)
 	}
 	return &builtPlugin{
-		name:    b.name,
-		version: b.version,
-		caps:    b.caps,
-		actions: b.actions,
-		rules:   b.rules,
+		name:          b.name,
+		version:       b.version,
+		caps:          b.caps,
+		actions:       b.actions,
+		rules:         b.rules,
+		skillsOverlay: b.skillsOverlay,
 	}, nil
 }
 
@@ -202,11 +246,12 @@ func (b *Builder) validateHookName(hookName, kind string) bool {
 
 // builtPlugin is the Plugin implementation the builder emits.
 type builtPlugin struct {
-	name    string
-	version string
-	caps    Capabilities
-	actions []func(Registrar)
-	rules   []*Rule
+	name          string
+	version       string
+	caps          Capabilities
+	actions       []func(Registrar)
+	rules         []*Rule
+	skillsOverlay *SkillsOverlay
 }
 
 func (p *builtPlugin) Name() string               { return p.name }
@@ -216,6 +261,9 @@ func (p *builtPlugin) Install(r Registrar) error {
 	for _, rule := range p.rules {
 		r.Restrict(rule)
 	}
+	if p.skillsOverlay != nil {
+		r.EmbeddedSkills(p.skillsOverlay)
+	}
 	for _, action := range p.actions {
 		action(r)
 	}

extension/platform/builder_test.go

@@ -14,11 +14,13 @@ import (
 // recorder Registrar captures everything a builder schedules so the
 // test can assert what Install produced without involving the host.
 type recorder struct {
-	observers  int
-	wrappers   int
-	lifecycles int
-	rule       *platform.Rule   // last rule (existing single-rule assertions)
-	rules      []*platform.Rule // every rule, in Restrict order
+	observers     int
+	wrappers      int
+	lifecycles    int
+	rule          *platform.Rule   // last rule (existing single-rule assertions)
+	rules         []*platform.Rule // every rule, in Restrict order
+	skillsOverlay *platform.SkillsOverlay
+	skillCalls    int
 }
 
 func (r *recorder) Observe(platform.When, string, platform.Selector, platform.Observer) {
@@ -30,6 +32,10 @@ func (r *recorder) Restrict(rule *platform.Rule) {
 	r.rule = rule
 	r.rules = append(r.rules, rule)
 }
+func (r *recorder) EmbeddedSkills(spec *platform.SkillsOverlay) {
+	r.skillsOverlay = spec
+	r.skillCalls++
+}
 
 // Restrict must snapshot each rule: a caller that reuses and mutates the
 // same *Rule object across two Restrict calls must still get two distinct
@@ -211,3 +217,78 @@ func TestBuilder_failOpenThenRestrictOK(t *testing.T) {
 		t.Errorf("FailurePolicy = %v, want FailClosed", p.Capabilities().FailurePolicy)
 	}
 }
+
+// EmbeddedSkills() must snapshot Remove: a caller that mutates the same slice
+// after the call must still get the value staged at call time.
+func TestBuilder_skillsInstalledAndCloned(t *testing.T) {
+	remove := []string{"lark-shared"}
+	b := platform.NewPlugin("p", "0").EmbeddedSkills(&platform.SkillsOverlay{Remove: remove})
+	remove[0] = "mutated"
+
+	p, err := b.Build()
+	if err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+	r := &recorder{}
+	if err := p.Install(r); err != nil {
+		t.Fatalf("Install: %v", err)
+	}
+	if r.skillCalls != 1 {
+		t.Fatalf("Skills calls = %d, want 1", r.skillCalls)
+	}
+	if r.skillsOverlay == nil || len(r.skillsOverlay.Remove) != 1 || r.skillsOverlay.Remove[0] != "lark-shared" {
+		t.Errorf("staged Remove leaked later mutation: %+v", r.skillsOverlay)
+	}
+}
+
+func TestBuilder_skillsNilRejected(t *testing.T) {
+	_, err := platform.NewPlugin("p", "0").EmbeddedSkills(nil).Build()
+	if err == nil {
+		t.Fatal("EmbeddedSkills(nil) must produce error")
+	}
+}
+
+func TestBuilder_skillsTwiceRejected(t *testing.T) {
+	_, err := platform.NewPlugin("p", "0").
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}).
+		EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-b"}}).
+		Build()
+	if err == nil {
+		t.Fatal("calling EmbeddedSkills() twice must produce error")
+	}
+}
+
+// EmbeddedSkills() customizes guidance content, not a security boundary, so
+// unlike Restrict() it must NOT force FailClosed.
+func TestBuilder_skillsDoesNotForceFailClosed(t *testing.T) {
+	p, err := platform.NewPlugin("p", "0").EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}}).Build()
+	if err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+	caps := p.Capabilities()
+	if caps.Restricts {
+		t.Error("EmbeddedSkills() must not set Restricts")
+	}
+	if caps.FailurePolicy != platform.FailOpen {
+		t.Errorf("FailurePolicy = %v, want FailOpen (default)", caps.FailurePolicy)
+	}
+}
+
+// HideDiagnostics only makes sense alongside Restrict: without a rule
+// there is no integrator policy whose inspection could be hidden.
+func TestBuilder_hideDiagnosticsRequiresRestrict(t *testing.T) {
+	_, err := platform.NewPlugin("p", "0").HideDiagnostics().Build()
+	if err == nil {
+		t.Fatal("HideDiagnostics() without Restrict() must fail Build")
+	}
+	p, err := platform.NewPlugin("p", "0").
+		Restrict(&platform.Rule{Deny: []string{"config/**"}}).
+		HideDiagnostics().
+		Build()
+	if err != nil {
+		t.Fatalf("HideDiagnostics()+Restrict() must build: %v", err)
+	}
+	if !p.Capabilities().HideDiagnostics {
+		t.Error("Capabilities.HideDiagnostics must be set")
+	}
+}

extension/platform/capabilities.go

@@ -47,4 +47,9 @@ type Capabilities struct {
 	// constants above; the framework requires FailClosed whenever
 	// Restricts=true.
 	FailurePolicy FailurePolicy
+
+	// HideDiagnostics retires the policy self-inspection commands
+	// (`config policy show`, `config plugins show`) from the build.
+	// Requires Restricts=true; the install fails otherwise.
+	HideDiagnostics bool
 }

extension/platform/registrar.go

@@ -35,4 +35,18 @@ type Registrar interface {
 	// Plugin rules take precedence over the yaml source; two distinct
 	// plugins both calling Restrict abort startup.
 	Restrict(r *Rule)
+
+	// Skills contributes a SkillsOverlay customizing the CLI's embedded skill
+	// content (see SkillsOverlay). Skill content has a single owner: a second
+	// customizing plugin, or a SkillsOverlay that cannot compose, aborts
+	// startup unconditionally. A malformed call inside one plugin --
+	// EmbeddedSkills(nil) or a second EmbeddedSkills() -- is a staging fault handled like
+	// any Install error (FailClosed aborts, FailOpen skips); the Builder
+	// rejects it earlier, at MustBuild.
+	//
+	// Unlike Restrict, EmbeddedSkills is not a security boundary -- it shapes
+	// fail-open guidance content. Removing a skill drops its guidance but
+	// does not disable any command; use Restrict to actually block a
+	// command.
+	EmbeddedSkills(spec *SkillsOverlay)
 }

extension/platform/rule.go

@@ -6,8 +6,9 @@ package platform
 // Rule is the declarative policy rule data structure. yaml files and
 // Plugin.Restrict() both produce the same Rule.
 //
-// At any moment there is at most one effective Rule -- the resolver decides
-// which source wins (Plugin > yaml > none). This package only defines the
+// At any moment there is at most one effective SOURCE of rules -- the
+// resolver decides which wins (Plugin > yaml > none); the winning source
+// may contribute several scoped rules. This package only defines the
 // shape; selection lives in internal/cmdpolicy.
 //
 // The four filter fields are joined by AND. See the engine's Evaluate for
@@ -57,4 +58,11 @@ type Rule struct {
 	// No yaml tag: yaml decoding lives in internal/cmdpolicy/yaml so
 	// platform stays free of a yaml library dependency.
 	AllowUnannotated bool `json:"allow_unannotated,omitempty"`
+
+	// DeniedMessage replaces the default "command not included in this
+	// build" message for plugin-denied commands. The message is
+	// build-level: the first non-empty DeniedMessage across the owning
+	// plugin's rules applies to every denial, so declare it once. yaml
+	// rules ignore it (they keep the command-denied presentation).
+	DeniedMessage string `json:"denied_message,omitempty"`
 }

extension/platform/skillsoverlay.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package platform
+
+import "io/fs"
+
+// SkillsOverlay declares how a plugin customizes the CLI's embedded
+// skill content, contributed via Builder.EmbeddedSkills. At most one
+// source may own skill content; two customizing plugins abort startup.
+//
+// Allow / Remove mirror Rule's Allow / Deny: an allow-list keeps only
+// what it names, a remove-list drops what it names, and Remove wins
+// over Allow. Composition order is fixed: Base (or the CLI default) ->
+// Allow -> Remove -> Overlay, a same-named skill resolving to Overlay.
+//
+// Skills are addressed by exact name (a directory carrying SKILL.md,
+// e.g. "lark-doc"), not by command path and not by glob — the skill
+// list is flat, so misspellings abort startup instead of silently
+// matching nothing. Removing a skill only drops its guidance; it does
+// not disable any command (use Restrict for that).
+type SkillsOverlay struct {
+	// Allow, when non-empty, keeps only these skills (by name) from the
+	// base tree — the allow-list counterpart of Rule.Allow. Skills the
+	// CLI adds in future versions stay out of the build until listed
+	// here, which a Remove-only spec cannot guarantee. A name not
+	// present in the base aborts startup. Overlay entries are exempt:
+	// content the integrator explicitly ships needs no allow-listing.
+	Allow []string
+
+	// Remove hides these skills, by name (e.g. "lark-shared"), from the
+	// base tree; it wins over Allow, mirroring Rule's Deny-over-Allow. A
+	// name not present in the base aborts startup rather than being
+	// silently ignored.
+	Remove []string
+
+	// Overlay contributes skills laid over the base: a same-named skill
+	// replaces the base's entirely, a new name adds one. It is rooted at
+	// the skill list (entries like "my-skill/SKILL.md"); each top-level
+	// entry must be a "<name>/" directory containing SKILL.md. Any fs.FS
+	// works (embed.FS, os.DirFS, fstest.MapFS); embed.FS is not required.
+	Overlay fs.FS
+
+	// Base replaces the entire base skill tree instead of layering over
+	// the CLI default. nil keeps the CLI default. Rare: most integrators
+	// leave it nil and use Remove/Overlay so unchanged skills follow the
+	// CLI version with no copy to maintain.
+	Base fs.FS
+}

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
-	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
+	github.com/larksuite/oapi-sdk-go/v3 v3.7.2
 	github.com/sergi/go-diff v1.4.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1

go.sum

@@ -79,8 +79,8 @@ github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORN
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
-github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/larksuite/oapi-sdk-go/v3 v3.7.2 h1:SCIcXHRmtpQbiaZgDTDi1NYNCzrusi7ePJBR9uKoduE=
+github.com/larksuite/oapi-sdk-go/v3 v3.7.2/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=

internal/affordance/affordance.go

@@ -83,10 +83,9 @@ func commandFormResolver(service string) func(string) string {
 		}
 	}
 	return func(h string) string {
-		h = strings.TrimSpace(h)
-		if id, ok := byForm[h]; ok {
+		if id, ok := byForm[strings.TrimSpace(h)]; ok {
 			return id
 		}
-		return strings.ReplaceAll(h, " ", ".")
+		return headingToKey(h) // one home for the shortcut/method key convention
 	}
 }

internal/affordance/affordance_test.go

@@ -7,6 +7,8 @@ import (
 	"encoding/json"
 	"testing"
 	"testing/fstest"
+
+	"github.com/larksuite/cli/internal/meta"
 )
 
 // fixtureMD is a minimal affordance source: two methods, each with a lead
@@ -84,3 +86,38 @@ func TestParseDomainMD_ParagraphNotDropped(t *testing.T) {
 		t.Errorf("custom-section paragraph not flowed through: %+v", a.Extensions)
 	}
 }
+
+// The ### Skills section merges with the domain `> skill:` default: domain
+// first, then per-command entries, de-duplicated. A command with no ### Skills
+// still inherits the domain default.
+func TestParseDomainMD_SkillsMerge(t *testing.T) {
+	md := "# d\n> skill: lark-d\n\n" +
+		"## foo\ndoes foo.\n\n### Skills\n- lark-workflow\n- lark-d\n\n" + // lark-d duplicates the domain default
+		"## bar\ndoes bar.\n"
+	got := parseDomainMD([]byte(md), nil)
+
+	if a := got["foo"]; len(a.Skills) != 2 || a.Skills[0] != "lark-d" || a.Skills[1] != "lark-workflow" {
+		t.Errorf("foo skills = %v, want [lark-d lark-workflow] (domain first, deduped)", a.Skills)
+	}
+	if a := got["bar"]; len(a.Skills) != 1 || a.Skills[0] != "lark-d" {
+		t.Errorf("bar skills = %v, want [lark-d] (domain default inherited)", a.Skills)
+	}
+}
+
+// A +-prefixed shortcut heading keys verbatim (no space->dot folding), so it
+// matches the shortcut command as mounted.
+func TestParseDomainMD_ShortcutHeadingVerbatim(t *testing.T) {
+	md := "# d\n\n## +create\ncreate via shortcut.\n"
+	got := parseDomainMD([]byte(md), nil)
+	if _, ok := got["+create"]; !ok {
+		t.Errorf("shortcut heading should key as %q; got keys %v", "+create", keysOf(got))
+	}
+}
+
+func keysOf(m map[string]meta.Affordance) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

internal/affordance/mdparse.go

@@ -19,6 +19,7 @@ import (
 //	### Prerequisites   -> prerequisites   (a "…来自 [[x]]" link is a sequence edge)
 //	### Tips            -> tips
 //	### Examples        -> examples: **description** + a ```fenced``` command
+//	### Skills          -> skills: bullet skill names, added to the domain default
 //	### <other>         -> extensions[] (custom section, flows through verbatim)
 //	[[cmd]]             -> a command reference, rendered as `cmd`
 //
@@ -34,16 +35,56 @@ var standardSection = map[string]string{
 	"Prerequisites": "prerequisites",
 	"Tips":          "tips",
 	"Examples":      "examples",
+	"Skills":        "skills",
+}
+
+// mergeSkills returns the domain-default skill followed by a command's own skill
+// entries, de-duplicated in author order and empties dropped. Backticks (left by
+// the shared bullet parse) are stripped so each entry is a bare skill name.
+func mergeSkills(domain string, extra []string) []string {
+	var out []string
+	seen := map[string]bool{}
+	add := func(s string) {
+		s = strings.Trim(strings.TrimSpace(s), "`")
+		if s == "" || seen[s] {
+			return
+		}
+		seen[s] = true
+		out = append(out, s)
+	}
+	add(domain)
+	for _, s := range extra {
+		add(s)
+	}
+	return out
 }
 
 func linkToBacktick(s string) string { return mdLink.ReplaceAllString(s, "`$1`") }
 
+// SkillStatPath maps a `### Skills` entry to the path (relative to the skill
+// tree) whose existence gates it: a bare skill name resolves to its SKILL.md,
+// while an entry containing a slash is a name/relative-path reference (e.g.
+// "lark-contact/references/lark-contact-search-user.md") and resolves to that
+// path directly. Both render as `lark-cli skills read <entry>` — the slash form
+// skills read already accepts — so a per-command entry can point at that
+// command's own reference file, not just re-point the domain skill.
+func SkillStatPath(entry string) string {
+	if strings.Contains(entry, "/") {
+		return entry
+	}
+	return entry + "/SKILL.md"
+}
+
 // headingToKey maps a command heading ("instances get") to its affordance key
 // ("instances.get"). The space→dot rule holds where the command form matches
 // the method id; domains whose resource names differ (e.g. plural "messages"
 // vs id segment "message") need the registry's authoritative resource↔id table.
 func headingToKey(h string) string {
-	return strings.ReplaceAll(strings.TrimSpace(h), " ", ".")
+	h = strings.TrimSpace(h)
+	if strings.HasPrefix(h, "+") { // shortcut command: key is the command verbatim
+		return h
+	}
+	return strings.ReplaceAll(h, " ", ".")
 }
 
 type mdSection struct {
@@ -82,6 +123,7 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 		if len(useWhen) > 0 {
 			a.UseWhen = useWhen
 		}
+		var perCmdSkills []string
 		for _, s := range secs {
 			switch standardSection[s.label] {
 			case "avoid_when":
@@ -92,12 +134,14 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				a.Tips = s.items
 			case "examples":
 				a.Examples = s.cases
+			case "skills":
+				perCmdSkills = s.items
 			default:
 				a.Extensions = append(a.Extensions, meta.AffordanceSection{Label: s.label, Items: s.items})
 			}
 		}
-		if skill != "" {
-			a.Skills = []string{skill}
+		if s := mergeSkills(skill, perCmdSkills); len(s) > 0 {
+			a.Skills = s
 		}
 		out[curKey] = a
 	}
@@ -157,7 +201,7 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				inFence, fence = true, nil
 			} else {
 				inFence = false
-				sec.cases = append(sec.cases, meta.AffordanceCase{Description: pending, Command: strings.Join(fence, "\n")})
+				sec.cases = append(sec.cases, meta.AffordanceCase{Description: linkToBacktick(pending), Command: strings.Join(fence, "\n")})
 				pending = ""
 			}
 			continue

internal/auth/errors.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 )
 
 const (
@@ -41,11 +42,15 @@ func (e *NeedAuthorizationError) Error() string {
 // legacy *NeedAuthorizationError sentinel is preserved in the Cause chain for
 // errors.As / errors.Is traversal.
 func NewNeedUserAuthorizationError(userOpenID string) *errs.AuthenticationError {
-	return errs.NewAuthenticationError(errs.SubtypeTokenMissing,
+	e := errs.NewAuthenticationError(errs.SubtypeTokenMissing,
 		"%s (user: %s)", needUserAuthorizationMarker, userOpenID).
 		WithUserOpenID(userOpenID).
-		WithHint("run: lark-cli auth login to re-authorize").
 		WithCause(&NeedAuthorizationError{UserOpenId: userOpenID})
+	// No recovery hint when the auth domain is absent from this build.
+	if !policystate.DomainDeniedByPlugin("auth") {
+		e = e.WithHint("run: lark-cli auth login to re-authorize")
+	}
+	return e
 }
 
 // IsNeedUserAuthorizationError reports whether err represents a missing-UAT

internal/auth/hint_gate_test.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/policystate"
+)
+
+// The auth-login recovery hint points into the auth domain; when an
+// integrator plugin denied that whole domain the hint would be a dead
+// end, so it stays off the error.
+func TestNeedUserAuthorization_hintFollowsAuthDomain(t *testing.T) {
+	t.Cleanup(policystate.ResetForTesting)
+
+	policystate.SetPluginDeniedDomains(nil)
+	if e := NewNeedUserAuthorizationError("ou_x"); !strings.Contains(e.Hint, "auth login") {
+		t.Errorf("default build must keep the auth login hint, got %q", e.Hint)
+	}
+
+	policystate.SetPluginDeniedDomains(map[string]bool{"auth": true})
+	if e := NewNeedUserAuthorizationError("ou_x"); e.Hint != "" {
+		t.Errorf("auth-denied build must not steer to auth login, got %q", e.Hint)
+	}
+}

internal/client/client.go

@@ -23,6 +23,7 @@ import (
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/policystate"
 	"github.com/larksuite/cli/internal/util"
 )
 
@@ -71,10 +72,14 @@ func (c *APIClient) resolveAccessToken(ctx context.Context, as core.Identity) (s
 // for the defensive empty-token branch) and is preserved for errors.Is /
 // errors.Unwrap traversal without being serialized on the wire.
 func newTokenMissingError(as core.Identity, cause error) error {
-	return errs.NewAuthenticationError(errs.SubtypeTokenMissing,
+	e := errs.NewAuthenticationError(errs.SubtypeTokenMissing,
 		"no access token available for %s", as).
-		WithHint("run: lark-cli auth login to re-authorize").
 		WithCause(cause)
+	// No recovery hint when the auth domain is absent from this build.
+	if !policystate.DomainDeniedByPlugin("auth") {
+		e = e.WithHint("run: lark-cli auth login to re-authorize")
+	}
+	return e
 }
 
 // buildApiReq converts a RawApiRequest into SDK types and collects

internal/client/hint_gate_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package client
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/policystate"
+)
+
+// Same gate as internal/auth: the token-missing recovery hint points into
+// the auth domain and stays off the error when a plugin denied it.
+func TestTokenMissing_hintFollowsAuthDomain(t *testing.T) {
+	t.Cleanup(policystate.ResetForTesting)
+
+	policystate.SetPluginDeniedDomains(nil)
+	var ae *errs.AuthenticationError
+	if err := newTokenMissingError(core.AsUser, nil); !errors.As(err, &ae) || !strings.Contains(ae.Hint, "auth login") {
+		t.Errorf("default build must keep the auth login hint, got %v", err)
+	}
+
+	policystate.SetPluginDeniedDomains(map[string]bool{"auth": true})
+	if err := newTokenMissingError(core.AsUser, nil); !errors.As(err, &ae) || ae.Hint != "" {
+		t.Errorf("auth-denied build must not steer to auth login, got %v", err)
+	}
+}

internal/cmdmeta/meta.go

@@ -2,9 +2,11 @@
 // SPDX-License-Identifier: MIT
 
 // Package cmdmeta is the single source of truth for command metadata that the
-// policy engine and the hook selector both consume. It wraps the existing
-// cmdutil annotations (risk_level, supportedIdentities) and adds the
-// "domain" axis that the hook selector and Rule path globs need.
+// policy engine, the hook selector, and help rendering consume. It wraps the
+// existing cmdutil annotations (risk_level, supportedIdentities) and adds the
+// "domain" axis that the hook selector and Rule path globs need, plus the
+// affordance ref (service, method id) that lets service-method and shortcut
+// help share one usage-guidance lookup path.
 //
 // Three axes:
 //
@@ -51,6 +53,12 @@ const (
 
 	sourceAnnotationKey    = "cmdmeta.source"
 	generatedAnnotationKey = "cmdmeta.generated"
+
+	// affordance{Service,Method}Key locate the command's usage-guidance overlay
+	// entry (see internal/affordance). Both service-method commands and
+	// +-prefixed shortcuts set these so help rendering shares one lookup path.
+	affordanceServiceKey = "cmdmeta.affordance.service"
+	affordanceMethodKey  = "cmdmeta.affordance.method"
 )
 
 // Meta groups the three command-level metadata axes consumed by the policy
@@ -125,6 +133,35 @@ func SetSource(cmd *cobra.Command, source Source, generated bool) {
 	}
 }
 
+// SetAffordanceRef records which affordance overlay entry (service, method id)
+// a command maps to, so help rendering can look up its usage guidance. Stored
+// on the command itself (no inheritance): each method / shortcut owns its ref.
+// A no-op if either coordinate is empty.
+func SetAffordanceRef(cmd *cobra.Command, service, method string) {
+	if service == "" || method == "" {
+		return
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[affordanceServiceKey] = service
+	cmd.Annotations[affordanceMethodKey] = method
+}
+
+// AffordanceRef returns the command's own affordance overlay coordinates.
+// ok is false when the command carries no ref.
+func AffordanceRef(cmd *cobra.Command) (service, method string, ok bool) {
+	if cmd.Annotations == nil {
+		return "", "", false
+	}
+	service = cmd.Annotations[affordanceServiceKey]
+	method = cmd.Annotations[affordanceMethodKey]
+	if service == "" || method == "" {
+		return "", "", false
+	}
+	return service, method, true
+}
+
 // Domain returns the nearest-ancestor domain for the command. Empty string
 // when no ancestor has the annotation -- this is the "unknown" state the
 // policy engine must treat as ALLOW.

internal/cmdpolicy/active.go

@@ -23,6 +23,9 @@ type ActivePolicy struct {
 	Rules       []*platform.Rule
 	Source      ResolveSource
 	DeniedPaths int // number of commands the engine marked as denied (post-aggregation)
+
+	// DeniedByPath is the full post-aggregation denial map.
+	DeniedByPath map[string]Denial
 }
 
 var (
@@ -81,6 +84,12 @@ func cloneActivePolicy(in *ActivePolicy) *ActivePolicy {
 			cp.Rules[i] = &rule
 		}
 	}
+	if in.DeniedByPath != nil {
+		cp.DeniedByPath = make(map[string]Denial, len(in.DeniedByPath))
+		for k, v := range in.DeniedByPath {
+			cp.DeniedByPath[k] = v
+		}
+	}
 	return &cp
 }
 

internal/cmdpolicy/aggregation_test.go

@@ -70,7 +70,7 @@ func TestBuildDeniedByPath_parentAggregationAllChildrenDenied(t *testing.T) {
 	}
 
 	denied := cmdpolicy.BuildDeniedByPath(root, decisions,
-		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: "/policy.yml"}, "agent")
+		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: "/policy.yml"}, "agent", "")
 
 	// Both leaves denied.
 	if _, ok := denied["im/+send"]; !ok {
@@ -110,7 +110,7 @@ func TestBuildDeniedByPath_partialDenialKeepsParent(t *testing.T) {
 		Deny:  []string{"docs/+delete"},
 	})
 	denied := cmdpolicy.BuildDeniedByPath(root, e.EvaluateAll(root),
-		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourcePlugin, Name: "secaudit"}, "secaudit-policy")
+		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourcePlugin, Name: "secaudit"}, "secaudit-policy", "")
 
 	if _, ok := denied["docs"]; ok {
 		t.Errorf("parent 'docs' must NOT be denied when some children are allowed")
@@ -129,7 +129,7 @@ func TestBuildDeniedByPath_rootNeverDenied(t *testing.T) {
 	root := buildTree()
 	e := cmdpolicy.New(&platform.Rule{Allow: []string{"nonexistent/**"}})
 	denied := cmdpolicy.BuildDeniedByPath(root, e.EvaluateAll(root),
-		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: "/p.yml"}, "")
+		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: "/p.yml"}, "", "")
 
 	// Every leaf should be denied. We do not assert on the root entry
 	// because Apply skips the root regardless; the contract is "root
@@ -156,7 +156,7 @@ func TestBuildDeniedByPath_hybridParentOwnAllowedKeepsAlive(t *testing.T) {
 		Allow: []string{"docs"},
 	})
 	denied := cmdpolicy.BuildDeniedByPath(root, e.EvaluateAll(root),
-		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: ""}, "")
+		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML, Name: ""}, "", "")
 
 	// docs/+delete denied (path doesn't match Allow=["docs"]).
 	if _, ok := denied["docs/+delete"]; !ok {
@@ -170,13 +170,13 @@ func TestBuildDeniedByPath_hybridParentOwnAllowedKeepsAlive(t *testing.T) {
 
 // Apply returns a typed *errs.ValidationError that exposes BOTH paths
 // consumers rely on:
-//  1. cmd/root.go's envelope writer (errs.ProblemOf / failed_precondition
-//     subtype + exit code 2)
+//  1. cmd/root.go's envelope writer (errs.ProblemOf; plugin-source
+//     denials use subtype command_unavailable + exit code 2)
 //  2. in-process consumers extracting the platform.CommandDeniedError as
 //     the typed error's Cause via errors.As
 //
-// The policy metadata (layer / policy_source / rule_name / reason_code)
-// is folded into the Hint text rather than a separate detail map.
+// Plugin-source denials keep the policy metadata OFF the wire (no hint,
+// no source / rule vocabulary); it stays reachable on the Cause only.
 func TestApply_runEReturnsExitErrorAndCommandDeniedError(t *testing.T) {
 	root := buildTree()
 	denied := map[string]cmdpolicy.Denial{
@@ -196,29 +196,31 @@ func TestApply_runEReturnsExitErrorAndCommandDeniedError(t *testing.T) {
 		t.Fatalf("denied command should return error")
 	}
 
-	// Path 1: typed-envelope view. The denial is a failed_precondition
-	// ValidationError so cmd/root.go renders the structured envelope and
-	// the process exits 2 (ExitValidation).
+	// Path 1: typed-envelope view. A plugin-source denial presents as
+	// "command unavailable": the capability is absent from this build, so
+	// the envelope carries no policy metadata and no recovery hint.
 	var ve *errs.ValidationError
 	if !errors.As(err, &ve) {
 		t.Fatalf("error chain must contain *errs.ValidationError, got %T", err)
 	}
-	if ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeFailedPrecondition)
+	if ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeCommandUnavailable)
 	}
 	if code := output.ExitCodeOf(err); code != output.ExitValidation {
 		t.Errorf("exit code = %d, want ExitValidation (%d)", code, output.ExitValidation)
 	}
-	// The policy metadata is folded into the Hint text: reason_code,
-	// policy_source, and rule_name must all be discoverable there.
-	if !strings.Contains(ve.Hint, "write_not_allowed") {
-		t.Errorf("hint must carry reason_code write_not_allowed, got %q", ve.Hint)
+	if ve.Message != cmdpolicy.DefaultUnavailableMessage {
+		t.Errorf("message = %q, want default unavailable message", ve.Message)
 	}
-	if !strings.Contains(ve.Hint, "plugin:secaudit") {
-		t.Errorf("hint must carry policy_source plugin:secaudit, got %q", ve.Hint)
+	// No hint, no policy vocabulary: the wire must not steer the caller
+	// toward a policy the integrator locked into the build.
+	if ve.Hint != "" {
+		t.Errorf("plugin-source denial must carry no hint, got %q", ve.Hint)
 	}
-	if !strings.Contains(ve.Hint, "secaudit-policy") {
-		t.Errorf("hint must carry rule_name secaudit-policy, got %q", ve.Hint)
+	for _, leak := range []string{"policy", "plugin:secaudit", "secaudit-policy", "write_not_allowed"} {
+		if strings.Contains(ve.Message, leak) {
+			t.Errorf("message leaks %q: %q", leak, ve.Message)
+		}
 	}
 
 	// Path 2: in-process typed-error view -- the *platform.CommandDeniedError
@@ -301,7 +303,7 @@ func TestHasRunnableDescendant_ignoresAnnotatedPureGroup(t *testing.T) {
 
 	e := cmdpolicy.New(&platform.Rule{MaxRisk: "read"})
 	decisions := e.EvaluateAll(root)
-	denied := cmdpolicy.BuildDeniedByPath(root, decisions, cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML}, "")
+	denied := cmdpolicy.BuildDeniedByPath(root, decisions, cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML}, "", "")
 
 	if _, ok := denied["docs"]; !ok {
 		t.Fatalf("docs should be aggregated as fully denied (pure-group children excluded from live count); map=%+v", denied)
@@ -332,7 +334,7 @@ func TestBuildDeniedByPath_aggregatesAnnotatedPureGroup(t *testing.T) {
 
 	e := cmdpolicy.New(&platform.Rule{MaxRisk: "read"})
 	decisions := e.EvaluateAll(root)
-	denied := cmdpolicy.BuildDeniedByPath(root, decisions, cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML}, "")
+	denied := cmdpolicy.BuildDeniedByPath(root, decisions, cmdpolicy.ResolveSource{Kind: cmdpolicy.SourceYAML}, "", "")
 
 	if _, ok := denied["drive"]; !ok {
 		t.Fatalf("aggregator must install drive denial when all children denied; map=%+v", denied)

internal/cmdpolicy/apply.go

@@ -4,6 +4,8 @@
 package cmdpolicy
 
 import (
+	"strings"
+
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/errs"
@@ -73,6 +75,10 @@ const (
 	AnnotationDenialLayer  = "lark:policy_denied_layer"
 	AnnotationDenialSource = "lark:policy_denied_source"
 
+	// AnnotationDenialMessage carries the resolved unavailable message
+	// for the cmd layer's help interceptor (plugin-source denials only).
+	AnnotationDenialMessage = "lark:policy_denied_message"
+
 	// AnnotationPureGroup marks a cobra.Command that is logically a
 	// parent-only group but had a RunE attached by the bootstrap-time
 	// unknown-subcommand guard. The engine treats annotated commands
@@ -124,6 +130,37 @@ func BuildDenialError(path string, d Denial) *errs.ValidationError {
 		WithCause(cd)
 }
 
+// IsPluginPolicySource reports whether a policy source names a plugin.
+// Plugin sources select the "command unavailable" presentation.
+func IsPluginPolicySource(source string) bool {
+	return strings.HasPrefix(source, "plugin:")
+}
+
+// DefaultUnavailableMessage is the message shown when a plugin-restricted
+// command is invoked and the integrator supplied no Rule.DeniedMessage.
+const DefaultUnavailableMessage = "command not included in this build"
+
+// messageOf resolves the effective unavailable message for a denial.
+func messageOf(d Denial) string {
+	if d.DeniedMessage != "" {
+		return d.DeniedMessage
+	}
+	return DefaultUnavailableMessage
+}
+
+// BuildUnavailableError is the plugin-source counterpart of
+// BuildDenialError: no hint, no policy vocabulary on the wire. The
+// *platform.CommandDeniedError stays reachable as the Cause for
+// in-process consumers; Cause is never serialized.
+func BuildUnavailableError(path string, d Denial) *errs.ValidationError {
+	msg := d.DeniedMessage
+	if msg == "" {
+		msg = DefaultUnavailableMessage
+	}
+	return errs.NewValidationError(errs.SubtypeCommandUnavailable, "%s", msg).
+		WithCause(CommandDeniedFromDenial(path, d))
+}
+
 // installDenyStub mutates a cobra.Command in place. Unlike cmd/prune.go
 // which does RemoveCommand+AddCommand (changing the pointer), we modify
 // the existing node so any external reference (snapshots, alias targets)
@@ -194,11 +231,19 @@ func installDenyStub(cmd *cobra.Command, path string, d Denial) bool {
 	cmd.Annotations[AnnotationDenialSource] = d.PolicySource
 
 	denial := d // capture by value for the closure
-	cmd.RunE = func(c *cobra.Command, args []string) error {
-		// The typed message carries the user-facing semantic ("a command
-		// was denied"); the hint carries the layer / source / rule
-		// distinction ("policy" vs "strict_mode") for debugging.
-		return BuildDenialError(path, denial)
+	if IsPluginPolicySource(d.PolicySource) {
+		// The message annotation feeds the cmd layer's help interceptor.
+		cmd.Annotations[AnnotationDenialMessage] = messageOf(d)
+		cmd.RunE = func(c *cobra.Command, args []string) error {
+			return BuildUnavailableError(path, denial)
+		}
+	} else {
+		cmd.RunE = func(c *cobra.Command, args []string) error {
+			// The typed message carries the user-facing semantic ("a command
+			// was denied"); the hint carries the layer / source / rule
+			// distinction ("policy" vs "strict_mode") for debugging.
+			return BuildDenialError(path, denial)
+		}
 	}
 	// Clear any pre-existing Run hook: cobra prefers RunE when both are
 	// set, but leaving a stale Run around is a foot-gun for future

internal/cmdpolicy/denial.go

@@ -25,6 +25,10 @@ type Denial struct {
 	RuleName     string // matched Rule.Name (if any)
 	ReasonCode   string // closed enum, see docs/extension/reason-codes.md
 	Reason       string // human-readable
+
+	// DeniedMessage is Rule.DeniedMessage for the plugin-source
+	// unavailable presentation; empty means the default message.
+	DeniedMessage string
 }
 
 // ChildDenial is what AggregateChildren consumes — it pairs a Denial

internal/cmdpolicy/diagnostic.go

@@ -27,3 +27,15 @@ var diagnosticPaths = map[string]bool{
 func IsDiagnosticPath(path string) bool {
 	return diagnosticPaths[path]
 }
+
+// DiagnosticPaths returns the exempt self-inspection command paths, for
+// the presentation layer: an integrator's HideDiagnostics retires exactly
+// this set, and the help-concealment pass hides it from listings when the
+// surrounding domain is plugin-denied.
+func DiagnosticPaths() []string {
+	out := make([]string, 0, len(diagnosticPaths))
+	for p := range diagnosticPaths {
+		out = append(out, p)
+	}
+	return out
+}

internal/cmdpolicy/engine.go

@@ -269,8 +269,9 @@ func mergeDenials(rules []*platform.Rule, denials []Decision) Decision {
 // so `--help` and similar remain available.
 //
 // source / ruleName populate PolicySource and RuleName on the produced
-// Denial values, so envelope output can attribute denials.
-func BuildDeniedByPath(root *cobra.Command, decisions map[string]Decision, source ResolveSource, ruleName string) map[string]Denial {
+// Denial values, so envelope output can attribute denials. deniedMessage
+// is build-level and applies uniformly, aggregates included.
+func BuildDeniedByPath(root *cobra.Command, decisions map[string]Decision, source ResolveSource, ruleName string, deniedMessage string) map[string]Denial {
 	out := map[string]Denial{}
 
 	sourceLabel := policySourceLabel(source)
@@ -287,6 +288,13 @@ func BuildDeniedByPath(root *cobra.Command, decisions map[string]Decision, sourc
 	}
 
 	aggregateParents(root, out)
+
+	if deniedMessage != "" {
+		for path, d := range out {
+			d.DeniedMessage = deniedMessage
+			out[path] = d
+		}
+	}
 	return out
 }
 

internal/cmdpolicy/source_label_test.go

@@ -34,7 +34,7 @@ func TestEnvelope_yamlPolicySourceDoesNotLeakHomePath(t *testing.T) {
 		cmdpolicy.ResolveSource{
 			Kind: cmdpolicy.SourceYAML,
 			Name: "/Users/alice/.lark-cli/policy.yml", // simulate an absolute path
-		}, "my-readonly-rule")
+		}, "my-readonly-rule", "")
 
 	cmdpolicy.Apply(root, denied)
 	err := leaf.RunE(leaf, nil)
@@ -77,7 +77,7 @@ func TestEnvelope_pluginPolicySourceCarriesName(t *testing.T) {
 	})
 	denied := cmdpolicy.BuildDeniedByPath(root, e.EvaluateAll(root),
 		cmdpolicy.ResolveSource{Kind: cmdpolicy.SourcePlugin, Name: "secaudit"},
-		"secaudit-policy")
+		"secaudit-policy", "")
 	cmdpolicy.Apply(root, denied)
 
 	err := leaf.RunE(leaf, nil)
@@ -85,10 +85,17 @@ func TestEnvelope_pluginPolicySourceCarriesName(t *testing.T) {
 	if !errors.As(err, &ve) {
 		t.Fatalf("expected *errs.ValidationError, got %T", err)
 	}
-	// The plugin name IS surfaced (in-binary, part of the contract): it
-	// must appear in the Hint so an integrator debugging a denial knows
-	// which plugin fired.
-	if !strings.Contains(ve.Hint, "plugin:secaudit") {
-		t.Errorf("hint must carry policy_source plugin:secaudit, got %q", ve.Hint)
+	// A plugin-source denial presents as absent: no hint, no plugin name
+	// on the wire. Plugin attribution moves to the in-process Cause
+	// (*platform.CommandDeniedError) for integrators debugging a denial.
+	if ve.Subtype != errs.SubtypeCommandUnavailable {
+		t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeCommandUnavailable)
+	}
+	if ve.Hint != "" || strings.Contains(ve.Message, "plugin:secaudit") {
+		t.Errorf("wire must not expose the plugin source; hint=%q message=%q", ve.Hint, ve.Message)
+	}
+	var cd *platform.CommandDeniedError
+	if !errors.As(err, &cd) || cd.PolicySource != "plugin:secaudit" {
+		t.Errorf("in-process Cause must carry plugin:secaudit, got %+v", cd)
 	}
 }

internal/cmdutil/fileupload.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"fmt"
 	"io"
+	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -128,7 +129,7 @@ func BuildFormdata(fileIO fileio.FileIO, fieldName, filePath string, isStdin boo
 				WithParam("--file").
 				WithCause(err)
 		}
-		fd.AddFile(fieldName, bytes.NewReader(data))
+		fd.AddFileWithName(fieldName, filepath.Base(filePath), bytes.NewReader(data))
 	}
 
 	// Add top-level JSON keys as text form fields.

internal/errclass/classify_test.go

@@ -113,6 +113,7 @@ func TestBuildAPIError_ExitCodeMatrix(t *testing.T) {
 		{"230027 user_not_authorized", 230027, errs.CategoryAuthorization, errs.SubtypeUserUnauthorized, 3, "PermissionError"},
 		{"1470403 task_permission_denied", 1470403, errs.CategoryAuthorization, errs.SubtypePermissionDenied, 3, "PermissionError"},
 		{"1470400 task_invalid_params", 1470400, errs.CategoryAPI, errs.SubtypeInvalidParameters, 1, "APIError"},
+		{"1062507 drive_parent_sibling_limit", 1062507, errs.CategoryAPI, errs.SubtypeQuotaExceeded, 1, "APIError"},
 		{"99991400 rate_limit", 99991400, errs.CategoryAPI, errs.SubtypeRateLimit, 1, "APIError"},
 		{"99991661 token_missing", 99991661, errs.CategoryAuthentication, errs.SubtypeTokenMissing, 3, "AuthenticationError"},
 		{"21000 challenge_required", 21000, errs.CategoryPolicy, errs.Subtype("challenge_required"), 6, "SecurityPolicyError"},

internal/errclass/codemeta_drive.go

@@ -17,6 +17,7 @@ var driveCodeMeta = map[int]CodeMeta{
 	1061043:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
 	1061044:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
 	1061101:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file quota exceeded
+	1062507:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // parent folder child count limit exceeded
 	1062009:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
 	1063001:   {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
 	1063002:   {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied

internal/meta/affordance.go

@@ -8,8 +8,11 @@ import "encoding/json"
 // Affordance is the typed usage guidance overlaid on a method. It is the single
 // model the envelope renderer and the command help both parse, so the
 // vocabulary is defined once; the JSON tags double as the envelope wire shape.
-// Skills entries are skill names (or name/path) rendered as runnable
-// `lark-cli skills read <entry>` pointers.
+// Skills entries are either a bare skill name (e.g. "lark-doc") or a
+// name/relative-path reference (e.g. "lark-contact/references/x.md"); both
+// render as runnable `lark-cli skills read <entry>` pointers. Help validates
+// each against the embedded skill tree (a name → its SKILL.md, a reference →
+// that path) and drops any that do not resolve.
 type Affordance struct {
 	UseWhen       []string            `json:"use_when,omitempty"`
 	AvoidWhen     []string            `json:"avoid_when,omitempty"`

internal/platform/error.go

@@ -53,4 +53,12 @@ const (
 	ReasonInstallPanic        = "install_panic"
 	ReasonDuplicatePluginName = "duplicate_plugin_name"
 	ReasonMultipleRestricts   = "multiple_restrict_plugins"
+	// ReasonInvalidSkillsOverlay flags a plugin's SkillsOverlay that cannot
+	// compose -- EmbeddedSkills() called twice, a Remove naming a skill absent
+	// from the base, or an Overlay entry missing SKILL.md.
+	ReasonInvalidSkillsOverlay = "invalid_skills_overlay"
+	// ReasonMultipleSkillsOverlays flags two or more plugins each contributing
+	// a SkillsOverlay; only one may own skill content (mirrors
+	// ReasonMultipleRestricts).
+	ReasonMultipleSkillsOverlays = "multiple_skills_overlay_plugins"
 )

internal/platform/host.go

@@ -11,6 +11,7 @@ import (
 	"github.com/larksuite/cli/extension/platform"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/hook"
+	"github.com/larksuite/cli/internal/skillpolicy"
 )
 
 // PluginInfo is the metadata of a successfully-installed plugin,
@@ -29,9 +30,10 @@ type PluginInfo struct {
 // every plugin that committed successfully (FailOpen-skipped plugins
 // are absent), for downstream diagnostics.
 type InstallResult struct {
-	Registry    *hook.Registry
-	PluginRules []cmdpolicy.PluginRule
-	Plugins     []PluginInfo
+	Registry     *hook.Registry
+	PluginRules  []cmdpolicy.PluginRule
+	PluginSkills []skillpolicy.PluginSkill
+	Plugins      []PluginInfo
 }
 
 // InstallAll runs every registered plugin through the staging
@@ -142,6 +144,16 @@ func installOne(name string, p platform.Plugin, result *InstallResult) error {
 		}
 	}
 
+	// The Builder rejects this at Build time; hand-written plugins are
+	// caught here (authoring error, aborts unconditionally).
+	if caps.HideDiagnostics && !caps.Restricts {
+		return &PluginInstallError{
+			PluginName: name,
+			ReasonCode: ReasonInvalidCapability,
+			Reason:     "HideDiagnostics=true requires Restricts=true",
+		}
+	}
+
 	// Version compatibility check. Two distinct failure modes:
 	//
 	//   1. Parse error (constraint is malformed, e.g. ">=abc")
@@ -207,6 +219,12 @@ func installOne(name string, p platform.Plugin, result *InstallResult) error {
 			Rule:       rule,
 		})
 	}
+	if staging.skillsOverlay != nil {
+		result.PluginSkills = append(result.PluginSkills, skillpolicy.PluginSkill{
+			PluginName:    name,
+			SkillsOverlay: staging.skillsOverlay,
+		})
+	}
 
 	// Record the plugin in the inventory. Version is fetched here under
 	// a recover-wrapped helper so a plugin's Version() panic does not

internal/platform/host_test.go

@@ -431,3 +431,79 @@ func TestInstallAll_multipleRestrictPerPlugin(t *testing.T) {
 			result.PluginRules[0].Rule.Name, result.PluginRules[1].Rule.Name)
 	}
 }
+
+// skillPlugin contributes a SkillsOverlay via r.EmbeddedSkills; the install pipeline
+// must capture it into PluginSkills for the skill resolver.
+type skillPlugin struct{}
+
+func (skillPlugin) Name() string    { return "skiller" }
+func (skillPlugin) Version() string { return "1.0.0" }
+func (skillPlugin) Capabilities() platform.Capabilities {
+	return platform.Capabilities{FailurePolicy: platform.FailOpen}
+}
+func (skillPlugin) Install(r platform.Registrar) error {
+	r.EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-shared"}})
+	return nil
+}
+
+func TestInstallAll_skillsCommitted(t *testing.T) {
+	result, err := internalplatform.InstallAll([]platform.Plugin{skillPlugin{}}, nil)
+	if err != nil {
+		t.Fatalf("InstallAll: %v", err)
+	}
+	if len(result.PluginSkills) != 1 {
+		t.Fatalf("PluginSkills = %d, want 1", len(result.PluginSkills))
+	}
+	ps := result.PluginSkills[0]
+	if ps.PluginName != "skiller" {
+		t.Errorf("PluginName = %q, want skiller", ps.PluginName)
+	}
+	if ps.SkillsOverlay == nil || len(ps.SkillsOverlay.Remove) != 1 || ps.SkillsOverlay.Remove[0] != "lark-shared" {
+		t.Errorf("Spec = %+v, want Remove=[lark-shared]", ps.SkillsOverlay)
+	}
+}
+
+// doubleSkillPlugin calls r.EmbeddedSkills twice; staging must reject it. Declared
+// FailClosed so the staging error aborts InstallAll deterministically.
+type doubleSkillPlugin struct{}
+
+func (doubleSkillPlugin) Name() string    { return "double-skiller" }
+func (doubleSkillPlugin) Version() string { return "1.0.0" }
+func (doubleSkillPlugin) Capabilities() platform.Capabilities {
+	return platform.Capabilities{FailurePolicy: platform.FailClosed}
+}
+func (doubleSkillPlugin) Install(r platform.Registrar) error {
+	r.EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-a"}})
+	r.EmbeddedSkills(&platform.SkillsOverlay{Remove: []string{"lark-b"}})
+	return nil
+}
+
+func TestInstallAll_skillsCalledTwice_aborts(t *testing.T) {
+	_, err := internalplatform.InstallAll([]platform.Plugin{doubleSkillPlugin{}}, nil)
+	if err == nil {
+		t.Fatal("calling r.EmbeddedSkills twice must abort a FailClosed plugin")
+	}
+	var pi *internalplatform.PluginInstallError
+	if !errors.As(err, &pi) || pi.ReasonCode != internalplatform.ReasonInvalidSkillsOverlay {
+		t.Errorf("err = %v, want PluginInstallError reason_code %s", err, internalplatform.ReasonInvalidSkillsOverlay)
+	}
+}
+
+// hideDiagnosticsOnlyPlugin declares HideDiagnostics without Restricts —
+// an authoring error the host rejects unconditionally.
+type hideDiagnosticsOnlyPlugin struct{}
+
+func (hideDiagnosticsOnlyPlugin) Name() string    { return "hider" }
+func (hideDiagnosticsOnlyPlugin) Version() string { return "1.0.0" }
+func (hideDiagnosticsOnlyPlugin) Capabilities() platform.Capabilities {
+	return platform.Capabilities{HideDiagnostics: true, FailurePolicy: platform.FailOpen}
+}
+func (hideDiagnosticsOnlyPlugin) Install(platform.Registrar) error { return nil }
+
+func TestInstallAll_hideDiagnosticsRequiresRestricts(t *testing.T) {
+	_, err := internalplatform.InstallAll([]platform.Plugin{hideDiagnosticsOnlyPlugin{}}, nil)
+	var pi *internalplatform.PluginInstallError
+	if !errors.As(err, &pi) || pi.ReasonCode != internalplatform.ReasonInvalidCapability {
+		t.Fatalf("HideDiagnostics without Restricts must abort with invalid_capability, got %v", err)
+	}
+}

internal/platform/inventory.go

@@ -29,6 +29,10 @@ type PluginEntry struct {
 	// plugin did not call r.Restrict.
 	Rules []*RuleView
 
+	// EmbeddedSkills summarises the plugin's EmbeddedSkills contribution;
+	// nil when the plugin did not customize embedded skills.
+	EmbeddedSkills *SkillsOverlayView `json:"embedded_skills,omitempty"`
+
 	Observers  []HookEntry
 	Wrappers   []HookEntry
 	Lifecycles []HookEntry
@@ -41,6 +45,7 @@ type CapabilitiesView struct {
 	Restricts          bool   `json:"restricts"`
 	FailurePolicy      string `json:"failure_policy"`
 	RequiredCLIVersion string `json:"required_cli_version,omitempty"`
+	HideDiagnostics    bool   `json:"hide_diagnostics,omitempty"`
 }
 
 // NewCapabilitiesView converts a platform.Capabilities value into the
@@ -50,6 +55,7 @@ func NewCapabilitiesView(c platform.Capabilities) CapabilitiesView {
 		Restricts:          c.Restricts,
 		FailurePolicy:      failurePolicyLabel(c.FailurePolicy),
 		RequiredCLIVersion: c.RequiredCLIVersion,
+		HideDiagnostics:    c.HideDiagnostics,
 	}
 }
 
@@ -74,6 +80,22 @@ type RuleView struct {
 	AllowUnannotated bool     `json:"allow_unannotated"`
 }
 
+// SkillsOverlayView is the displayable summary of an EmbeddedSkills
+// contribution. Overlay / Base report presence only (an fs.FS has no
+// display form).
+type SkillsOverlayView struct {
+	Allow   []string `json:"allow,omitempty"`
+	Remove  []string `json:"remove,omitempty"`
+	Overlay bool     `json:"overlay"`
+	Base    bool     `json:"base"`
+}
+
+// SkillsInventorySource pairs a plugin name with its overlay summary.
+type SkillsInventorySource struct {
+	PluginName string
+	View       SkillsOverlayView
+}
+
 // Inventory is the full snapshot.
 type Inventory struct {
 	Plugins []PluginEntry
@@ -108,7 +130,7 @@ type RuleInventorySource struct {
 // Hooks are attributed to plugins by the namespaced name convention:
 // each entry's Name starts with "<plugin>.", and we group by the
 // leading segment up to the first dot.
-func BuildInventory(plugins []PluginInventorySource, registry *hook.Registry, rules []RuleInventorySource) *Inventory {
+func BuildInventory(plugins []PluginInventorySource, registry *hook.Registry, rules []RuleInventorySource, skills []SkillsInventorySource) *Inventory {
 	byPlugin := make(map[string]*PluginEntry, len(plugins))
 	out := &Inventory{Plugins: make([]PluginEntry, 0, len(plugins))}
 	for _, p := range plugins {
@@ -162,6 +184,15 @@ func BuildInventory(plugins []PluginInventorySource, registry *hook.Registry, ru
 			})
 		}
 	}
+
+	for _, sk := range skills {
+		if entry := byPlugin[sk.PluginName]; entry != nil {
+			v := sk.View
+			v.Allow = append([]string(nil), sk.View.Allow...)
+			v.Remove = append([]string(nil), sk.View.Remove...)
+			entry.EmbeddedSkills = &v
+		}
+	}
 	return out
 }
 
@@ -263,6 +294,12 @@ func cloneInventory(in *Inventory) *Inventory {
 				entry.Rules[j] = &rv
 			}
 		}
+		if p.EmbeddedSkills != nil {
+			sv := *p.EmbeddedSkills
+			sv.Allow = append([]string(nil), p.EmbeddedSkills.Allow...)
+			sv.Remove = append([]string(nil), p.EmbeddedSkills.Remove...)
+			entry.EmbeddedSkills = &sv
+		}
 		entry.Observers = append([]HookEntry(nil), p.Observers...)
 		entry.Wrappers = append([]HookEntry(nil), p.Wrappers...)
 		entry.Lifecycles = append([]HookEntry(nil), p.Lifecycles...)

internal/platform/inventory_test.go

@@ -36,7 +36,7 @@ func TestBuildInventory_groupsByPluginName(t *testing.T) {
 		{PluginName: "a", RuleName: "a-rule", Allow: []string{"docs/**"}, MaxRisk: "read"},
 	}
 
-	inv := internalplatform.BuildInventory(plugins, r, rules)
+	inv := internalplatform.BuildInventory(plugins, r, rules, nil)
 
 	if got := len(inv.Plugins); got != 2 {
 		t.Fatalf("Plugins len = %d, want 2", got)
@@ -89,7 +89,7 @@ func TestBuildInventory_multipleRulesPerPlugin(t *testing.T) {
 		{PluginName: "a", RuleName: "im-rw", Allow: []string{"im/**"}, MaxRisk: "write"},
 	}
 
-	inv := internalplatform.BuildInventory(plugins, nil, rules)
+	inv := internalplatform.BuildInventory(plugins, nil, rules, nil)
 	a := findPlugin(inv, "a")
 	if a == nil {
 		t.Fatalf("missing entry a")
@@ -103,12 +103,45 @@ func TestBuildInventory_multipleRulesPerPlugin(t *testing.T) {
 }
 
 func TestBuildInventory_empty(t *testing.T) {
-	inv := internalplatform.BuildInventory(nil, nil, nil)
+	inv := internalplatform.BuildInventory(nil, nil, nil, nil)
 	if got := len(inv.Plugins); got != 0 {
 		t.Errorf("Plugins len = %d, want 0", got)
 	}
 }
 
+// A non-nil SkillsInventorySource must surface on the owning plugin's entry as
+// an EmbeddedSkills summary, and BuildInventory must clone the Allow/Remove
+// slices so a later mutation of the source cannot corrupt the recorded view.
+func TestBuildInventory_populatesAndClonesEmbeddedSkills(t *testing.T) {
+	plugins := []internalplatform.PluginInventorySource{{Name: "acme", Version: "1.0"}}
+	allow := []string{"lark-im"}
+	remove := []string{"lark-shared"}
+	skills := []internalplatform.SkillsInventorySource{
+		{PluginName: "acme", View: internalplatform.SkillsOverlayView{
+			Allow: allow, Remove: remove, Overlay: true, Base: false,
+		}},
+	}
+
+	inv := internalplatform.BuildInventory(plugins, nil, nil, skills)
+	entry := findPlugin(inv, "acme")
+	if entry == nil || entry.EmbeddedSkills == nil {
+		t.Fatalf("acme entry missing EmbeddedSkills: %+v", entry)
+	}
+	es := entry.EmbeddedSkills
+	if len(es.Allow) != 1 || es.Allow[0] != "lark-im" ||
+		len(es.Remove) != 1 || es.Remove[0] != "lark-shared" ||
+		!es.Overlay || es.Base {
+		t.Errorf("EmbeddedSkills summary mismatch: %+v", es)
+	}
+
+	// Mutating the source slices must not leak into the recorded view.
+	allow[0] = "MUTATED"
+	remove[0] = "MUTATED"
+	if es.Allow[0] != "lark-im" || es.Remove[0] != "lark-shared" {
+		t.Errorf("EmbeddedSkills slices not cloned; source mutation leaked: %+v", es)
+	}
+}
+
 func findPlugin(inv *internalplatform.Inventory, name string) *internalplatform.PluginEntry {
 	for i := range inv.Plugins {
 		if inv.Plugins[i].Name == name {

internal/platform/staging.go

@@ -41,6 +41,13 @@ type stagingRegistrar struct {
 	// can detect the call.
 	actuallyRestricted bool
 
+	// skillsOverlay holds the staged Skills contribution, captured for the
+	// host to feed into the skill resolver later. nil means the plugin
+	// did not call r.EmbeddedSkills. overlaySet records that the call happened so a
+	// second call in the same plugin can be rejected.
+	skillsOverlay *platform.SkillsOverlay
+	overlaySet    bool
+
 	// seenHookNames detects duplicate hookName within this plugin's
 	// Install call.
 	seenHookNames map[string]bool
@@ -144,6 +151,25 @@ func (r *stagingRegistrar) Restrict(rule *platform.Rule) {
 	r.rules = append(r.rules, &cp)
 }
 
+func (r *stagingRegistrar) EmbeddedSkills(spec *platform.SkillsOverlay) {
+	if r.overlaySet {
+		r.bufferErr(ReasonInvalidSkillsOverlay, "EmbeddedSkills() called more than once in the same plugin")
+		return
+	}
+	r.overlaySet = true
+	if spec == nil {
+		r.bufferErr(ReasonInvalidSkillsOverlay, "EmbeddedSkills(nil)")
+		return
+	}
+	// Defensive clone: freeze Remove so a plugin cannot mutate it after
+	// Install returns. Overlay/Base are read-only fs.FS views retained by
+	// reference.
+	cp := *spec
+	cp.Allow = append([]string(nil), spec.Allow...)
+	cp.Remove = append([]string(nil), spec.Remove...)
+	r.skillsOverlay = &cp
+}
+
 // --- helpers ---
 
 func (r *stagingRegistrar) namespaced(name string) string {

internal/policystate/policystate.go

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package policystate answers "did an integrator plugin deny this whole
+// command domain?" for render-time hint emitters. It is dependency-free
+// because internal/auth and internal/client sit below internal/cmdpolicy
+// in the import graph and cannot ask it directly. Written once by the
+// bootstrap after policy pruning; read-only thereafter.
+package policystate
+
+import "sync"
+
+var (
+	mu                  sync.RWMutex
+	pluginDeniedDomains map[string]bool
+)
+
+// SetPluginDeniedDomains records the plugin-denied top-level domains.
+// nil clears.
+func SetPluginDeniedDomains(domains map[string]bool) {
+	mu.Lock()
+	defer mu.Unlock()
+	if domains == nil {
+		pluginDeniedDomains = nil
+		return
+	}
+	cp := make(map[string]bool, len(domains))
+	for d, v := range domains {
+		cp[d] = v
+	}
+	pluginDeniedDomains = cp
+}
+
+// DomainDeniedByPlugin reports whether the whole top-level domain was
+// denied by an integrator plugin. yaml denials never register here.
+func DomainDeniedByPlugin(domain string) bool {
+	mu.RLock()
+	defer mu.RUnlock()
+	return pluginDeniedDomains[domain]
+}
+
+// ResetForTesting clears the recorded state.
+func ResetForTesting() {
+	mu.Lock()
+	defer mu.Unlock()
+	pluginDeniedDomains = nil
+}

internal/skillpolicy/overlay.go

@@ -0,0 +1,209 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillpolicy
+
+import (
+	"io"
+	"io/fs"
+	"sort"
+	"strings"
+	"time"
+)
+
+// overlayFS layers an upper skill tree over a lower one at skill (top
+// path segment) granularity: a skill present in upper is served wholly
+// from upper, a skill named in removed is hidden, and everything else
+// falls through to lower. It is the runtime form of a SkillsOverlay's
+// Base -> Remove -> Overlay composition.
+//
+// It implements the io/fs fast-path interfaces (ReadDir/Stat/ReadFile)
+// so the io/fs helpers route through the merge instead of hitting a
+// single underlying tree.
+type overlayFS struct {
+	lower      fs.FS           // base (or SkillsOverlay.Base); may be nil
+	upper      fs.FS           // SkillsOverlay.Overlay; may be nil
+	removed    map[string]bool // skill names whited out from lower
+	upperNames map[string]bool // skill names owned by upper
+}
+
+var (
+	_ fs.FS         = (*overlayFS)(nil)
+	_ fs.ReadDirFS  = (*overlayFS)(nil)
+	_ fs.StatFS     = (*overlayFS)(nil)
+	_ fs.ReadFileFS = (*overlayFS)(nil)
+)
+
+func newOverlayFS(lower, upper fs.FS, remove []string) *overlayFS {
+	o := &overlayFS{
+		lower:      lower,
+		upper:      upper,
+		removed:    make(map[string]bool, len(remove)),
+		upperNames: map[string]bool{},
+	}
+	for _, r := range remove {
+		o.removed[r] = true
+	}
+	if upper != nil {
+		if entries, err := fs.ReadDir(upper, "."); err == nil {
+			for _, e := range entries {
+				if e.IsDir() {
+					o.upperNames[e.Name()] = true
+				}
+			}
+		}
+	}
+	return o
+}
+
+// route picks the tree owning name by its top path segment. whiteout is
+// true when name belongs to a removed skill (present in neither tree).
+func (o *overlayFS) route(name string) (target fs.FS, whiteout bool) {
+	top := name
+	if i := strings.IndexByte(name, '/'); i >= 0 {
+		top = name[:i]
+	}
+	switch {
+	case o.upperNames[top]:
+		return o.upper, false
+	case o.removed[top]:
+		return nil, true
+	default:
+		return o.lower, false
+	}
+}
+
+func (o *overlayFS) Open(name string) (fs.File, error) {
+	if !fs.ValidPath(name) {
+		return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrInvalid}
+	}
+	if name == "." {
+		entries, err := o.ReadDir(".")
+		if err != nil {
+			return nil, err
+		}
+		return &rootDir{entries: entries}, nil
+	}
+	target, whiteout := o.route(name)
+	if whiteout || target == nil {
+		return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
+	}
+	return target.Open(name)
+}
+
+func (o *overlayFS) Stat(name string) (fs.FileInfo, error) {
+	if !fs.ValidPath(name) {
+		return nil, &fs.PathError{Op: "stat", Path: name, Err: fs.ErrInvalid}
+	}
+	if name == "." {
+		return rootInfo{}, nil
+	}
+	target, whiteout := o.route(name)
+	if whiteout || target == nil {
+		return nil, &fs.PathError{Op: "stat", Path: name, Err: fs.ErrNotExist}
+	}
+	return fs.Stat(target, name)
+}
+
+func (o *overlayFS) ReadFile(name string) ([]byte, error) {
+	if !fs.ValidPath(name) || name == "." {
+		return nil, &fs.PathError{Op: "readfile", Path: name, Err: fs.ErrInvalid}
+	}
+	target, whiteout := o.route(name)
+	if whiteout || target == nil {
+		return nil, &fs.PathError{Op: "readfile", Path: name, Err: fs.ErrNotExist}
+	}
+	return fs.ReadFile(target, name)
+}
+
+func (o *overlayFS) ReadDir(name string) ([]fs.DirEntry, error) {
+	if !fs.ValidPath(name) {
+		return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrInvalid}
+	}
+	if name != "." {
+		target, whiteout := o.route(name)
+		if whiteout || target == nil {
+			return nil, &fs.PathError{Op: "readdir", Path: name, Err: fs.ErrNotExist}
+		}
+		return fs.ReadDir(target, name)
+	}
+	return o.mergedRoot()
+}
+
+// mergedRoot lists the top-level skills: every upper skill, plus every
+// lower skill that is neither removed nor shadowed by a same-named upper.
+// Sorted so listings are deterministic.
+func (o *overlayFS) mergedRoot() ([]fs.DirEntry, error) {
+	seen := map[string]bool{}
+	var out []fs.DirEntry
+	if o.upper != nil {
+		entries, err := fs.ReadDir(o.upper, ".")
+		if err != nil {
+			return nil, err
+		}
+		for _, e := range entries {
+			if !e.IsDir() {
+				continue
+			}
+			out = append(out, e)
+			seen[e.Name()] = true
+		}
+	}
+	if o.lower != nil {
+		entries, err := fs.ReadDir(o.lower, ".")
+		if err != nil {
+			return nil, err
+		}
+		for _, e := range entries {
+			if o.removed[e.Name()] || seen[e.Name()] {
+				continue
+			}
+			out = append(out, e)
+			seen[e.Name()] = true
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name() < out[j].Name() })
+	return out, nil
+}
+
+// rootInfo is the synthetic FileInfo for the overlay's "." directory,
+// which has no single backing entry in either tree.
+type rootInfo struct{}
+
+func (rootInfo) Name() string       { return "." }
+func (rootInfo) Size() int64        { return 0 }
+func (rootInfo) Mode() fs.FileMode  { return fs.ModeDir | 0o555 }
+func (rootInfo) ModTime() time.Time { return time.Time{} }
+func (rootInfo) IsDir() bool        { return true }
+func (rootInfo) Sys() any           { return nil }
+
+// rootDir is the synthetic directory file returned by Open(".").
+type rootDir struct {
+	entries []fs.DirEntry
+	off     int
+}
+
+func (d *rootDir) Stat() (fs.FileInfo, error) { return rootInfo{}, nil }
+func (d *rootDir) Close() error               { return nil }
+
+func (d *rootDir) Read([]byte) (int, error) {
+	return 0, &fs.PathError{Op: "read", Path: ".", Err: fs.ErrInvalid}
+}
+
+func (d *rootDir) ReadDir(n int) ([]fs.DirEntry, error) {
+	if n <= 0 {
+		rest := d.entries[d.off:]
+		d.off = len(d.entries)
+		return rest, nil
+	}
+	if d.off >= len(d.entries) {
+		return nil, io.EOF
+	}
+	end := d.off + n
+	if end > len(d.entries) {
+		end = len(d.entries)
+	}
+	part := d.entries[d.off:end]
+	d.off = end
+	return part, nil
+}

internal/skillpolicy/resolver.go

@@ -0,0 +1,156 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package skillpolicy composes the CLI's effective embedded skill tree
+// from a base skill FS and at most one plugin-supplied SkillsOverlay. It is
+// the skill-side analogue of internal/cmdpolicy: plugins contribute a
+// delta over a base, and one resolver produces the single tree that both
+// skill readers consume -- `skills list`/`read` and the --help
+// domain-guide pointer.
+package skillpolicy
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"strings"
+
+	"github.com/larksuite/cli/extension/platform"
+)
+
+// PluginSkill pairs a plugin name with the SkillsOverlay it contributed, so a
+// conflict can be attributed to specific owners. Mirrors
+// cmdpolicy.PluginRule.
+type PluginSkill struct {
+	PluginName    string
+	SkillsOverlay *platform.SkillsOverlay
+}
+
+// ErrMultipleSkillsOverlays reports that more than one plugin tried to
+// customize skill content. Mirrors cmdpolicy.ErrMultipleRestricts: only
+// one owner is allowed so independent plugins cannot silently overwrite
+// each other's skill tree.
+var ErrMultipleSkillsOverlays = errors.New("multiple plugins customized skills; only one plugin may own skill content")
+
+// Resolve composes the effective skill tree from base and the supplied
+// specs. base is the CLI's embedded skill FS (nil when the build embeds
+// none). With no spec it returns base unchanged. With exactly one spec it
+// applies, in fixed order, Base override -> Allow -> Remove -> Overlay,
+// returning an overlay FS in which a same-named skill resolves to
+// Overlay. Two or more distinct owners is a configuration error.
+func Resolve(base fs.FS, specs []PluginSkill) (fs.FS, error) {
+	owners := distinctOwners(specs)
+	if len(owners) > 1 {
+		return nil, fmt.Errorf("%w: %v", ErrMultipleSkillsOverlays, owners)
+	}
+	if len(specs) == 0 || specs[0].SkillsOverlay == nil {
+		return base, nil
+	}
+
+	owner, spec := specs[0].PluginName, specs[0].SkillsOverlay
+	lower := base
+	if spec.Base != nil {
+		lower = spec.Base
+	}
+	if err := validate(lower, spec); err != nil {
+		return nil, fmt.Errorf("plugin %q skill spec: %w", owner, err)
+	}
+	if lower == nil && spec.Overlay == nil {
+		return nil, nil
+	}
+	return newOverlayFS(lower, spec.Overlay, effectiveRemove(lower, spec)), nil
+}
+
+// effectiveRemove folds a non-empty Allow into the remove set: every
+// base skill not allow-listed is treated as removed, and explicit
+// Remove entries win regardless (Remove-over-Allow, mirroring Rule's
+// Deny-over-Allow). Overlay entries are never folded in — the overlay
+// FS resolves them from the upper layer before the whiteout applies.
+func effectiveRemove(lower fs.FS, spec *platform.SkillsOverlay) []string {
+	if len(spec.Allow) == 0 {
+		return spec.Remove
+	}
+	allowed := map[string]bool{}
+	for _, name := range spec.Allow {
+		allowed[name] = true
+	}
+	removed := append([]string(nil), spec.Remove...)
+	entries, err := fs.ReadDir(lower, ".")
+	if err != nil {
+		return removed // validate already vetted lower; nothing more to fold
+	}
+	for _, e := range entries {
+		if e.IsDir() && !allowed[e.Name()] {
+			removed = append(removed, e.Name())
+		}
+	}
+	return removed
+}
+
+// distinctOwners returns the unique contributing plugin names in
+// first-seen order. Mirrors cmdpolicy.distinctOwners.
+func distinctOwners(specs []PluginSkill) []string {
+	seen := map[string]bool{}
+	owners := make([]string, 0, len(specs))
+	for _, s := range specs {
+		if !seen[s.PluginName] {
+			seen[s.PluginName] = true
+			owners = append(owners, s.PluginName)
+		}
+	}
+	return owners
+}
+
+// validate rejects a spec that cannot compose cleanly, so the failure
+// surfaces at startup with a named cause rather than as a silently
+// missing skill at read time.
+func validate(lower fs.FS, spec *platform.SkillsOverlay) error {
+	for _, name := range spec.Allow {
+		if !isSkillName(name) {
+			return fmt.Errorf("Allow: %q is not a valid skill name", name)
+		}
+		if !skillExists(lower, name) {
+			return fmt.Errorf("Allow: skill %q is not in the base tree", name)
+		}
+	}
+	for _, name := range spec.Remove {
+		if !isSkillName(name) {
+			return fmt.Errorf("Remove: %q is not a valid skill name", name)
+		}
+		if !skillExists(lower, name) {
+			return fmt.Errorf("Remove: skill %q is not in the base tree", name)
+		}
+	}
+	if spec.Overlay != nil {
+		entries, err := fs.ReadDir(spec.Overlay, ".")
+		if err != nil {
+			return fmt.Errorf("Overlay: cannot read root: %w", err)
+		}
+		for _, e := range entries {
+			if !e.IsDir() {
+				return fmt.Errorf("Overlay: %q is not a directory; every Overlay entry must be a <skill>/ dir", e.Name())
+			}
+			if !skillExists(spec.Overlay, e.Name()) {
+				return fmt.Errorf("Overlay: skill %q is missing SKILL.md", e.Name())
+			}
+		}
+	}
+	return nil
+}
+
+// skillExists reports whether fsys holds a skill named name -- a
+// directory carrying SKILL.md, the shape internal/skillcontent treats as
+// a skill.
+func skillExists(fsys fs.FS, name string) bool {
+	if fsys == nil {
+		return false
+	}
+	info, err := fs.Stat(fsys, name+"/SKILL.md")
+	return err == nil && !info.IsDir()
+}
+
+// isSkillName rejects empty, dotted, or path-bearing names so Remove
+// cannot smuggle a traversal or match outside the top level.
+func isSkillName(name string) bool {
+	return name != "" && name != "." && name != ".." && !strings.ContainsAny(name, `/\`)
+}

internal/skillpolicy/resolver_test.go

@@ -0,0 +1,272 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package skillpolicy
+
+import (
+	"errors"
+	"io/fs"
+	"sort"
+	"testing"
+	"testing/fstest"
+
+	"github.com/larksuite/cli/extension/platform"
+)
+
+// skillFS builds an in-memory skill tree; each map entry is a path -> content.
+func skillFS(files map[string]string) fstest.MapFS {
+	m := fstest.MapFS{}
+	for p, content := range files {
+		m[p] = &fstest.MapFile{Data: []byte(content)}
+	}
+	return m
+}
+
+// baseTree is a representative base: three skills, one with a reference file.
+func baseTree() fstest.MapFS {
+	return skillFS(map[string]string{
+		"lark-a/SKILL.md":        "base a",
+		"lark-a/references/x.md": "base a ref",
+		"lark-b/SKILL.md":        "base b",
+		"lark-shared/SKILL.md":   "base shared",
+	})
+}
+
+// topLevel returns the sorted top-level skill names of fsys.
+func topLevel(t *testing.T, fsys fs.FS) []string {
+	t.Helper()
+	entries, err := fs.ReadDir(fsys, ".")
+	if err != nil {
+		t.Fatalf("ReadDir(.): %v", err)
+	}
+	var names []string
+	for _, e := range entries {
+		names = append(names, e.Name())
+	}
+	sort.Strings(names)
+	return names
+}
+
+func readFile(t *testing.T, fsys fs.FS, name string) string {
+	t.Helper()
+	data, err := fs.ReadFile(fsys, name)
+	if err != nil {
+		t.Fatalf("ReadFile(%q): %v", name, err)
+	}
+	return string(data)
+}
+
+func mustResolve(t *testing.T, base fs.FS, spec *platform.SkillsOverlay) fs.FS {
+	t.Helper()
+	got, err := Resolve(base, []PluginSkill{{PluginName: "acme", SkillsOverlay: spec}})
+	if err != nil {
+		t.Fatalf("Resolve: unexpected error: %v", err)
+	}
+	return got
+}
+
+func TestResolve_NoSpecs_ReturnsBaseUnchanged(t *testing.T) {
+	base := baseTree()
+	got, err := Resolve(base, nil)
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if want := []string{"lark-a", "lark-b", "lark-shared"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+}
+
+func TestResolve_Remove_HidesSkill(t *testing.T) {
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{Remove: []string{"lark-shared"}})
+
+	if want := []string{"lark-a", "lark-b"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+	// The removed skill is gone for the affordance reader too (Stat gates it).
+	if _, err := fs.Stat(got, "lark-shared/SKILL.md"); !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("Stat removed skill: err = %v, want ErrNotExist", err)
+	}
+	// Surviving skills still read from base.
+	if c := readFile(t, got, "lark-a/SKILL.md"); c != "base a" {
+		t.Errorf("lark-a content = %q, want %q", c, "base a")
+	}
+}
+
+func TestResolve_Overlay_AddsNewSkill(t *testing.T) {
+	overlay := skillFS(map[string]string{"lark-new/SKILL.md": "new skill"})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{Overlay: overlay})
+
+	if want := []string{"lark-a", "lark-b", "lark-new", "lark-shared"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+	if c := readFile(t, got, "lark-new/SKILL.md"); c != "new skill" {
+		t.Errorf("lark-new content = %q, want %q", c, "new skill")
+	}
+}
+
+func TestResolve_Overlay_ReplacesSameNameWholeSkill(t *testing.T) {
+	overlay := skillFS(map[string]string{"lark-a/SKILL.md": "overlaid a"})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{Overlay: overlay})
+
+	// Same-named skill resolves to the overlay (upper wins).
+	if c := readFile(t, got, "lark-a/SKILL.md"); c != "overlaid a" {
+		t.Errorf("lark-a content = %q, want overlaid", c)
+	}
+	// Replacement is whole-skill: the base's reference file is shadowed, not merged.
+	if _, err := fs.Stat(got, "lark-a/references/x.md"); !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("base reference should be shadowed by overlay skill; err = %v, want ErrNotExist", err)
+	}
+}
+
+func TestResolve_Base_ReplacesEntireTree(t *testing.T) {
+	replacement := skillFS(map[string]string{"lark-only/SKILL.md": "only"})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{Base: replacement})
+
+	if want := []string{"lark-only"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+	if _, err := fs.Stat(got, "lark-a/SKILL.md"); !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("base skill should be gone after Base replace; err = %v", err)
+	}
+}
+
+func TestResolve_Base_WithRemoveAndOverlay(t *testing.T) {
+	replacement := skillFS(map[string]string{
+		"lark-p/SKILL.md": "p",
+		"lark-q/SKILL.md": "q",
+	})
+	overlay := skillFS(map[string]string{"lark-r/SKILL.md": "r"})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{
+		Base:    replacement,
+		Remove:  []string{"lark-q"},
+		Overlay: overlay,
+	})
+	if want := []string{"lark-p", "lark-r"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+}
+
+// Allow keeps only the listed base skills — the allow-list counterpart
+// of Rule.Allow, so a CLI upgrade adding new embedded skills cannot
+// widen an allow-listed build.
+func TestResolve_Allow_KeepsOnlyListed(t *testing.T) {
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{Allow: []string{"lark-a"}})
+
+	if want := []string{"lark-a"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+	if _, err := fs.Stat(got, "lark-b/SKILL.md"); !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("non-allow-listed skill must be absent; err = %v", err)
+	}
+	// Kept skills still read from base, references included.
+	if c := readFile(t, got, "lark-a/references/x.md"); c != "base a ref" {
+		t.Errorf("kept skill content = %q, want base content", c)
+	}
+}
+
+// Remove wins over Allow, mirroring Rule's Deny-over-Allow.
+func TestResolve_RemoveWinsOverAllow(t *testing.T) {
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{
+		Allow:  []string{"lark-a", "lark-b"},
+		Remove: []string{"lark-b"},
+	})
+	if want := []string{"lark-a"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+}
+
+// Overlay entries are exempt from Allow: content the integrator
+// explicitly ships needs no allow-listing.
+func TestResolve_OverlayExemptFromAllow(t *testing.T) {
+	overlay := skillFS(map[string]string{"acme-guide/SKILL.md": "mine"})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{
+		Allow:   []string{"lark-a"},
+		Overlay: overlay,
+	})
+	if want := []string{"acme-guide", "lark-a"}; !equalStrings(topLevel(t, got), want) {
+		t.Errorf("top level = %v, want %v", topLevel(t, got), want)
+	}
+}
+
+// An Allow name absent from the base aborts startup, same as Remove.
+func TestResolve_AllowUnknown_Errors(t *testing.T) {
+	_, err := Resolve(baseTree(), []PluginSkill{{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Allow: []string{"lark-nope"}}}})
+	if err == nil {
+		t.Fatal("expected error allow-listing a skill absent from base")
+	}
+}
+
+func TestResolve_RemoveUnknown_Errors(t *testing.T) {
+	_, err := Resolve(baseTree(), []PluginSkill{{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Remove: []string{"lark-nope"}}}})
+	if err == nil {
+		t.Fatal("expected error removing a skill absent from base")
+	}
+}
+
+func TestResolve_RemoveInvalidName_Errors(t *testing.T) {
+	for _, bad := range []string{"", ".", "..", "a/b", `a\b`} {
+		if _, err := Resolve(baseTree(), []PluginSkill{{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Remove: []string{bad}}}}); err == nil {
+			t.Errorf("Remove %q: expected error, got nil", bad)
+		}
+	}
+}
+
+func TestResolve_OverlayMissingSKILLmd_Errors(t *testing.T) {
+	overlay := skillFS(map[string]string{"lark-bad/other.md": "no skill.md here"})
+	_, err := Resolve(baseTree(), []PluginSkill{{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Overlay: overlay}}})
+	if err == nil {
+		t.Fatal("expected error for overlay entry missing SKILL.md")
+	}
+}
+
+func TestResolve_OverlayNonDirEntry_Errors(t *testing.T) {
+	overlay := skillFS(map[string]string{"loose.md": "top-level file, not a skill dir"})
+	_, err := Resolve(baseTree(), []PluginSkill{{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Overlay: overlay}}})
+	if err == nil {
+		t.Fatal("expected error for non-directory overlay entry")
+	}
+}
+
+func TestResolve_TwoOwners_Errors(t *testing.T) {
+	_, err := Resolve(baseTree(), []PluginSkill{
+		{PluginName: "acme", SkillsOverlay: &platform.SkillsOverlay{Remove: []string{"lark-a"}}},
+		{PluginName: "globex", SkillsOverlay: &platform.SkillsOverlay{Remove: []string{"lark-b"}}},
+	})
+	if !errors.Is(err, ErrMultipleSkillsOverlays) {
+		t.Fatalf("err = %v, want ErrMultipleSkillsOverlays", err)
+	}
+}
+
+// TestResolve_ComposedConformsToFS runs the composed tree through the
+// standard io/fs conformance checker to catch Open/ReadDir/Stat drift.
+func TestResolve_ComposedConformsToFS(t *testing.T) {
+	overlay := skillFS(map[string]string{
+		"lark-new/SKILL.md":        "new",
+		"lark-new/references/y.md": "new ref",
+	})
+	got := mustResolve(t, baseTree(), &platform.SkillsOverlay{
+		Remove:  []string{"lark-shared"},
+		Overlay: overlay,
+	})
+	if err := fstest.TestFS(got,
+		"lark-a/SKILL.md",
+		"lark-a/references/x.md",
+		"lark-b/SKILL.md",
+		"lark-new/SKILL.md",
+		"lark-new/references/y.md",
+	); err != nil {
+		t.Fatalf("composed FS failed fs conformance: %v", err)
+	}
+}
+
+func equalStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

package.json

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

shortcuts/base/record_json_shorthand_test.go

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func mountBaseShortcutFlags(t *testing.T, s common.Shortcut, name string) *cobra.Command {
+	t.Helper()
+	parent := &cobra.Command{Use: "test"}
+	s.Mount(parent, &cmdutil.Factory{})
+	cmd, _, err := parent.Find([]string{name})
+	if err != nil {
+		t.Fatalf("Find(%s) error = %v", name, err)
+	}
+	return cmd
+}
+
+// record-list 获得 --json 简写
+func TestRecordListRegistersJSONShorthand(t *testing.T) {
+	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("+record-list missing --json shorthand")
+	}
+	if fl.Usage != "shorthand for --format json" {
+		t.Errorf("usage = %q, want shorthand", fl.Usage)
+	}
+	if def := cmd.Flags().Lookup("format").DefValue; def != "markdown" {
+		t.Errorf("format default = %q, want markdown (unchanged)", def)
+	}
+}
+
+// record-search / record-get 的 --json 保持请求体语义，不被覆盖（回归锚点）
+func TestRecordSearchGetKeepRequestBodyJSON(t *testing.T) {
+	for _, tc := range []struct {
+		name     string
+		shortcut common.Shortcut
+		cmdName  string
+	}{
+		{"record-search", BaseRecordSearch, "+record-search"},
+		{"record-get", BaseRecordGet, "+record-get"},
+	} {
+		cmd := mountBaseShortcutFlags(t, tc.shortcut, tc.cmdName)
+		fl := cmd.Flags().Lookup("json")
+		if fl == nil {
+			t.Fatalf("%s: --json (request body) missing", tc.name)
+		}
+		if strings.Contains(fl.Usage, "shorthand") {
+			t.Fatalf("%s: request-body --json overwritten by shorthand: %q", tc.name, fl.Usage)
+		}
+		if fl.Value.Type() != "string" {
+			t.Fatalf("%s: --json type = %q, want string", tc.name, fl.Value.Type())
+		}
+	}
+}
+
+// Enum 已接入：help 描述携带枚举后缀（框架对带 Enum 的 flag 自动追加 " (markdown|json)"）
+func TestRecordReadFormatFlagCarriesEnum(t *testing.T) {
+	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
+	usage := cmd.Flags().Lookup("format").Usage
+	if !strings.Contains(usage, "(markdown|json)") {
+		t.Fatalf("format usage missing enum suffix: %q", usage)
+	}
+}

shortcuts/base/record_list.go

@@ -85,6 +85,7 @@ func recordReadFormatFlag() common.Flag {
 	return common.Flag{
 		Name:    "format",
 		Default: "markdown",
+		Enum:    []string{"markdown", "json"},
 		Desc:    "output format: markdown (default) | json",
 	}
 }

shortcuts/common/runner.go

@@ -889,6 +889,7 @@ func (s Shortcut) mountDeclarative(ctx context.Context, parent *cobra.Command, f
 		}
 	}
 	cmdmeta.SetSource(cmd, cmdmeta.SourceShortcut, false)
+	cmdmeta.SetAffordanceRef(cmd, shortcut.Service, shortcut.Command)
 	cmdutil.SetSupportedIdentities(cmd, shortcut.AuthTypes)
 	registerShortcutFlagsWithContext(ctx, cmd, f, &shortcut)
 	cmdutil.SetTips(cmd, shortcut.Tips)
@@ -1026,6 +1027,7 @@ func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, conf
 	}
 	rctx.larkSDK = sdk
 
+	applyJSONShorthand(cmd, s)
 	rctx.Format = rctx.Str("format")
 	rctx.JqExpr, _ = cmd.Flags().GetString("jq")
 	return rctx, nil
@@ -1171,6 +1173,75 @@ func registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut)
 	registerShortcutFlagsWithContext(context.Background(), cmd, f, s)
 }
 
+// shortcutDeclaresJSONFlag reports whether the shortcut itself declares a flag
+// named "json" in its Flags list (custom semantics, e.g. event +subscribe's
+// pretty-print switch or base +record-search's request-body payload).
+// Framework-injected flags never appear in s.Flags, so this cleanly separates
+// "self-declared json" from "injected shorthand".
+func shortcutDeclaresJSONFlag(s *Shortcut) bool {
+	for _, fl := range s.Flags {
+		if fl.Name == "json" {
+			return true
+		}
+	}
+	return false
+}
+
+// shortcutFormatSupportsJSON reports whether the command's format flag accepts
+// "json": a self-declared format supports it only when its Enum lists "json";
+// a framework-injected default format (no format entry in s.Flags) always does.
+func shortcutFormatSupportsJSON(s *Shortcut) bool {
+	for _, fl := range s.Flags {
+		if fl.Name == "format" {
+			return slices.Contains(fl.Enum, "json")
+		}
+	}
+	return true // framework-injected: json (default) | pretty | table | ndjson | csv
+}
+
+// ensureJSONShorthand registers --json as a shorthand for --format json when:
+//  1. the command has a format flag (self-declared or framework-injected), AND
+//  2. that format supports "json" (see shortcutFormatSupportsJSON), AND
+//  3. no flag named "json" is registered yet — pflag panics on duplicate
+//     registration, and commands that declare their own --json (event
+//     +subscribe, base +record-search/-get) keep their custom semantics.
+func ensureJSONShorthand(cmd *cobra.Command, s *Shortcut) {
+	// A shortcut that declares its own "json" flag defines custom semantics
+	// (e.g. pretty-print switch, request-body payload) — never a shorthand.
+	if shortcutDeclaresJSONFlag(s) {
+		return
+	}
+	if cmd.Flags().Lookup("format") == nil {
+		return
+	}
+	if !shortcutFormatSupportsJSON(s) {
+		return
+	}
+	// Safety net: pflag panics on duplicate registration.
+	if cmd.Flags().Lookup("json") != nil {
+		return
+	}
+	cmd.Flags().Bool("json", false, "shorthand for --format json")
+}
+
+// applyJSONShorthand folds the injected --json shorthand into the format flag
+// itself, before rctx.Format caches it — so both the cached value (OutFormat,
+// ValidateJqFlags, dry-run) and later runtime.Str("format") reads observe
+// "json". An explicitly passed --format always wins over the shorthand (the
+// shorthand only fills in when the user did not choose a format). Shortcuts
+// that declare their own "json" flag keep its custom semantics untouched.
+func applyJSONShorthand(cmd *cobra.Command, s *Shortcut) {
+	if shortcutDeclaresJSONFlag(s) {
+		return
+	}
+	if cmd.Flags().Lookup("json") == nil || cmd.Flags().Changed("format") {
+		return
+	}
+	if set, _ := cmd.Flags().GetBool("json"); set {
+		_ = cmd.Flags().Set("format", "json")
+	}
+}
+
 func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
 	for _, fl := range s.Flags {
 		desc := fl.Desc
@@ -1234,10 +1305,8 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 		cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 			return []string{"json", "pretty", "table", "ndjson", "csv"}, cobra.ShellCompDirectiveNoFileComp
 		})
-		if cmd.Flags().Lookup("json") == nil {
-			cmd.Flags().Bool("json", false, "shorthand for --format json")
-		}
 	}
+	ensureJSONShorthand(cmd, s)
 	if s.Risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}

shortcuts/common/runner_json_shorthand_test.go

@@ -0,0 +1,200 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package common
+
+import (
+	"context"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+const jsonShorthandUsage = "shorthand for --format json"
+
+func mountTestShortcut(t *testing.T, s Shortcut) *cobra.Command {
+	t.Helper()
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	parent := &cobra.Command{Use: "root"}
+	s.Mount(parent, f)
+	cmd, _, err := parent.Find([]string{s.Command})
+	if err != nil {
+		t.Fatalf("Find() error = %v", err)
+	}
+	return cmd
+}
+
+// 自定义 format 且 Enum 含 json → 注册简写（本次修复的核心行为）
+func TestJSONShorthand_CustomFormatWithJSONEnum_Registered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "mail", Command: "+fake-triage", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("--json not registered for custom-format shortcut whose Enum contains json")
+	}
+	if fl.Usage != jsonShorthandUsage {
+		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
+	}
+	// 默认输出格式不被改变
+	if def := cmd.Flags().Lookup("format").DefValue; def != "table" {
+		t.Errorf("format default = %q, want table", def)
+	}
+}
+
+// 自定义 format 但 Enum 不含 json → 不注册
+func TestJSONShorthand_CustomFormatWithoutJSONEnum_NotRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "x", Command: "+no-json", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "csv", Enum: []string{"csv", "table"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	if cmd.Flags().Lookup("json") != nil {
+		t.Fatal("--json must NOT be registered when format Enum lacks json")
+	}
+}
+
+// 自定义 format 但无 Enum（现状 triage 形态）→ 不注册（Enum 是判定依据）
+func TestJSONShorthand_CustomFormatNoEnum_NotRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "x", Command: "+legacy", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	if cmd.Flags().Lookup("json") != nil {
+		t.Fatal("--json must NOT be registered when format has no Enum metadata")
+	}
+}
+
+// 自声明 json flag（subscribe 的 pretty / record-search 的请求体）→ 不覆盖、不 panic、语义保留
+func TestJSONShorthand_SelfDeclaredJSON_Preserved(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "event", Command: "+fake-subscribe", Description: "x",
+		Flags: []Flag{
+			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("self-declared --json missing")
+	}
+	if fl.Usage != "pretty-print JSON instead of NDJSON" {
+		t.Errorf("self-declared --json usage overwritten: %q", fl.Usage)
+	}
+}
+
+// parseMounted mounts the shortcut and parses args against the command's FlagSet
+// (registration side effects included), without executing RunE.
+func parseMounted(t *testing.T, s Shortcut, args []string) *cobra.Command {
+	t.Helper()
+	cmd := mountTestShortcut(t, s)
+	if err := cmd.ParseFlags(args); err != nil {
+		t.Fatalf("ParseFlags(%v) error = %v", args, err)
+	}
+	return cmd
+}
+
+func customFormatShortcut() Shortcut {
+	return Shortcut{
+		Service: "mail", Command: "+fake-triage", Description: "x",
+		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+}
+
+// --json 单独使用 → format 归一化为 json
+func TestApplyJSONShorthand_JSONAlone_SetsFormatJSON(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
+		t.Fatalf("format = %q, want json", got)
+	}
+}
+
+// 显式 --format 优先于 --json 简写：--format table --json → table
+func TestApplyJSONShorthand_ExplicitFormatWins(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--format", "table", "--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
+		t.Fatalf("format = %q, want table (explicit --format must win)", got)
+	}
+}
+
+// --format json --json → json（一致，无冲突）
+func TestApplyJSONShorthand_ExplicitJSONFormatConsistent(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, []string{"--format", "json", "--json"})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
+		t.Fatalf("format = %q, want json", got)
+	}
+}
+
+// 均不传 → 默认值不变
+func TestApplyJSONShorthand_NoFlags_DefaultUntouched(t *testing.T) {
+	s := customFormatShortcut()
+	cmd := parseMounted(t, s, nil)
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
+		t.Fatalf("format = %q, want table (default untouched)", got)
+	}
+}
+
+// 自声明 string 型 --json（record-search 形态：format+json 双声明）→ 归一化跳过
+func TestApplyJSONShorthand_SelfDeclaredStringJSON_Skipped(t *testing.T) {
+	s := Shortcut{
+		Service: "base", Command: "+fake-record-search", Description: "x",
+		Flags: []Flag{
+			{Name: "format", Default: "markdown", Enum: []string{"markdown", "json"}, Desc: "fmt"},
+			{Name: "json", Desc: "request body JSON object"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+	cmd := parseMounted(t, s, []string{"--json", `{"keyword":"Alice"}`})
+	applyJSONShorthand(cmd, &s)
+	if got := cmd.Flags().Lookup("format").Value.String(); got != "markdown" {
+		t.Fatalf("format = %q, want markdown (self-declared json must not normalize)", got)
+	}
+	if got := cmd.Flags().Lookup("json").Value.String(); got != `{"keyword":"Alice"}` {
+		t.Fatalf("request-body --json corrupted: %q", got)
+	}
+}
+
+// 自声明 bool 型 --json（subscribe 形态：无自定义 format，框架注入 format）→ 归一化跳过
+func TestApplyJSONShorthand_SelfDeclaredBoolJSON_Skipped(t *testing.T) {
+	s := Shortcut{
+		Service: "event", Command: "+fake-subscribe", Description: "x",
+		Flags: []Flag{
+			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
+		},
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	}
+	cmd := parseMounted(t, s, []string{"--json"})
+	applyJSONShorthand(cmd, &s)
+	// 注入的 format 默认即 json；这里断言的是 Changed 状态未被归一化污染
+	if cmd.Flags().Changed("format") {
+		t.Fatal("normalization must not touch format for shortcuts declaring their own --json")
+	}
+}
+
+// 无自定义 format（普通命令）→ 注入默认 format + 简写（现状回归）
+func TestJSONShorthand_DefaultInjectedFormat_StillRegistered(t *testing.T) {
+	cmd := mountTestShortcut(t, Shortcut{
+		Service: "im", Command: "+plain", Description: "x",
+		Execute: func(context.Context, *RuntimeContext) error { return nil },
+	})
+	fl := cmd.Flags().Lookup("json")
+	if fl == nil {
+		t.Fatal("--json missing on default-format shortcut (regression)")
+	}
+	if fl.Usage != jsonShorthandUsage {
+		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
+	}
+}

shortcuts/contact/contact_search_user.go

@@ -150,12 +150,10 @@ var ContactSearchUser = common.Shortcut{
 		{Name: "queries", Desc: "comma-separated keywords searched in parallel; output is a flat users[] with matched_query plus a queries[] sidecar"},
 	},
 	Tips: []string{
-		"Keyword search: lark-cli contact +search-user --query 'alice'",
-		"Look up by ID (or 'me' for self): lark-cli contact +search-user --user-ids 'ou_xxx,me'",
 		"Filter-only enumeration — users you've chatted with: lark-cli contact +search-user --has-chatted",
 		"Refine same-name hits: lark-cli contact +search-user --query '张三' --has-chatted --exclude-external-users",
 		"Multi-name fanout: lark-cli contact +search-user --queries 'alice,bob,张三'",
-		"open_id is the stable identifier for follow-up commands; on has_more=true add filters or tighten --query — there is no auto-pagination.",
+		"on has_more=true add filters or tighten --query — there is no auto-pagination.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateSearchUser(runtime)

shortcuts/drive/drive_push.go

@@ -623,6 +623,10 @@ func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
 	case problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400:
 		decision.Class = "rate_limited"
 		decision.Terminal = true
+	case problem.Code == 1062507:
+		decision.Class = "parent_sibling_limit"
+		decision.Terminal = true
+		decision.Hint = "The destination parent folder has reached its child-count limit. Clean up that folder, choose another --folder-token, or split the upload across subfolders before retrying."
 	case problem.Subtype == errs.SubtypeQuotaExceeded || problem.Code == 1061043:
 		decision.Class = "file_size_limit"
 	case problem.Code == 1062009:

shortcuts/drive/drive_push_test.go

@@ -1334,6 +1334,75 @@ func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
 	}
 }
 
+func TestDrivePushAbortsAfterCreateFolderParentSiblingLimit(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "a"), 0o755); err != nil {
+		t.Fatalf("MkdirAll a: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join("local", "b"), 0o755); err != nil {
+		t.Fatalf("MkdirAll b: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 1062507,
+			"msg":  "parent node out of sibling num.",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "a" || item["phase"] != "create_folder" || item["error_class"] != "parent_sibling_limit" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1062507) || item["subtype"] != "quota_exceeded" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["hint"].(string); !strings.Contains(got, "--folder-token") || !strings.Contains(got, "child-count limit") {
+		t.Fatalf("hint should explain the destination folder child-count limit, got item=%#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b" {
+			t.Fatalf("parent sibling limit must abort before b, got items=%#v", items)
+		}
+	}
+}
+
 func TestDrivePushDetectsLocalFileChangedBeforeUpload(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 

shortcuts/mail/mail_json_shorthand_test.go

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// help 必须列出 --json 简写
+func TestMailTriageHelpListsJSONShorthand(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcutWithCobraOutput(t, MailTriage, []string{"+triage", "-h"}, f, stdout); err != nil {
+		t.Fatalf("help returned error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "shorthand for --format json") {
+		t.Fatalf("triage help missing --json shorthand\n%s", stdout.String())
+	}
+}
+
+func TestMailWatchHelpListsJSONShorthand(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcutWithCobraOutput(t, MailWatch, []string{"+watch", "-h"}, f, stdout); err != nil {
+		t.Fatalf("help returned error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "shorthand for --format json") {
+		t.Fatalf("watch help missing --json shorthand\n%s", stdout.String())
+	}
+}
+
+// 行为验证：--json 走 JSON 输出路径，不输出 table read hint
+func TestMailTriageJSONShorthandDoesNotEmitReadHint(t *testing.T) {
+	f, stdout, stderr, reg := mailShortcutTestFactory(t)
+	registerTriageReadHintStubs(reg)
+
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1"}, f, stdout)
+	if err != nil {
+		t.Fatalf("triage --json returned error: %v", err)
+	}
+	reg.Verify(t)
+	if strings.Contains(stderr.String(), "tip: read full content:") {
+		t.Fatalf("--json must follow the JSON path, got table hint\nstderr=%s", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"messages"`) {
+		t.Fatalf("--json stdout missing JSON payload\n%s", stdout.String())
+	}
+}
+
+// 等价性验证：--json 与 --format json 的 dry-run 输出一致
+func TestMailTriageJSONShorthandDryRunEquivalence(t *testing.T) {
+	f1, stdout1, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1", "--dry-run"}, f1, stdout1); err != nil {
+		t.Fatalf("--json --dry-run error: %v", err)
+	}
+	f2, stdout2, _, _ := mailShortcutTestFactory(t)
+	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "json", "--max", "1", "--dry-run"}, f2, stdout2); err != nil {
+		t.Fatalf("--format json --dry-run error: %v", err)
+	}
+	if stdout1.String() != stdout2.String() {
+		t.Fatalf("dry-run outputs differ:\n--json:\n%s\n--format json:\n%s", stdout1.String(), stdout2.String())
+	}
+}
+
+// 优先级验证：显式 --format table 优先，--json 让位 → 仍走 table 路径
+func TestMailTriageExplicitTableWinsOverJSONShorthand(t *testing.T) {
+	f, stdout, stderr, reg := mailShortcutTestFactory(t)
+	registerTriageReadHintStubs(reg)
+
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "table", "--json", "--max", "1"}, f, stdout)
+	if err != nil {
+		t.Fatalf("triage returned error: %v", err)
+	}
+	if !strings.Contains(stderr.String(), "tip: read full content:") {
+		t.Fatalf("explicit --format table must win over --json (expected table hint)\nstderr=%s", stderr.String())
+	}
+}
+
+// 错误验证：Enum 硬校验
+func TestMailTriageEnumRejectsUnknownFormat(t *testing.T) {
+	f, stdout, _, _ := mailShortcutTestFactory(t)
+	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "bogus", "--max", "1", "--dry-run"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected validation error for --format bogus")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %T, want typed errs problem carrier", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("error = %T, want *errs.ValidationError", err)
+	}
+	if ve.Param != "--format" {
+		t.Fatalf("param = %q, want --format", ve.Param)
+	}
+	if !strings.Contains(problem.Message, `invalid value "bogus" for --format`) {
+		t.Fatalf("message = %q, want enum validation message", problem.Message)
+	}
+	if !strings.Contains(problem.Message, "table, json, data") {
+		t.Fatalf("message = %q, want allowed values list", problem.Message)
+	}
+}

shortcuts/mail/mail_triage.go

@@ -55,7 +55,7 @@ var MailTriage = common.Shortcut{
 	Scopes:      []string{"mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "table", Desc: "output format: table | json | data (json/data output object with pagination fields)"},
+		{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "output format: table | json | data (json/data output object with pagination fields)"},
 		{Name: "max", Type: "int", Default: "20", Desc: "maximum number of messages to fetch (1-400; auto-paginates internally)"},
 		{Name: "page-size", Type: "int", Desc: "alias for --max"},
 		{Name: "page-token", Desc: "pagination token from a previous response to fetch the next page"},

shortcuts/mail/mail_watch.go

@@ -99,7 +99,7 @@ var MailWatch = common.Shortcut{
 	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
+		{Name: "format", Default: "data", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
 		{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
 		{Name: "output-dir", Desc: "Write each message as a JSON file (always full payload, regardless of --msg-format)"},
 		{Name: "mailbox", Default: "me", Desc: "email address (default: me)"},

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -21,6 +21,8 @@ metadata:
 ## 快速决策
 
 - 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
+- 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 `lark-cli drive +inspect --url '<url>'` 进行识别；具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。
+- 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
@@ -162,7 +164,7 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 
 > **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
 >
-> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，必须按 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) 的模板通过 `--params` 传 `folder_token` / `page_token`，并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
+> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，使用前先读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)，按模板通过 `--params` 传参并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
 
 ### files
 
@@ -204,10 +206,12 @@ lark-cli drive <resource> <method> [flags] # 调用 API
 ### file.statistics
 
   - `get` — 获取文件统计信息
+    - 获取 docx / 文件统计信息时，建议优先使用 typed flags：`lark-cli drive file.statistics get --file-token <token> --file-type <type> --format json`；`--params` JSON 也支持，适合批量拼装或 raw 参数场景。
 
 ### file.view_records
 
   - `list` — 获取文档的访问者记录
+    - 查看 docx 最近访问记录、返回 open_id、最多 N 条时，建议优先使用 typed flags：`lark-cli drive file.view_records list --file-token <docx_token> --file-type docx --page-size <N> --viewer-id-type open_id --format json`；`--params` JSON 也支持，适合批量拼装、分页续跑或 raw 参数场景。
 
 ### file.comment.reply.reactions
 

skills/lark-drive/references/lark-drive-delete.md

@@ -7,6 +7,18 @@
 
 > [!CAUTION]
 > 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
+> “目标明确”表示用户给出了可解析为 `file-token` + `type` 的具体 URL/token，或对你刚列出的可解析资源列表逐项/整批确认删除。按“没用的”“临时的”“疑似重复的”“全部旧文件”等描述搜索出来的候选属于待确认目标；这类请求先列候选、说明筛选依据和影响范围，然后停止等待确认。
+
+## 删除前门槛
+
+执行 `drive +delete --yes` 前同时满足：
+
+| 条件 | 可执行信号 |
+|------|------------|
+| 具体目标 | 单个可解析为 `file-token` + `type` 的 URL/token，或用户确认过且可解析的资源列表 |
+| 执行确认 | 用户在本轮明确说确认删除这些具体目标 |
+
+若缺少任一条件，使用 `drive +search`、`drive +inspect` 或只读 API 收集候选并回复待确认清单；启发式规则（打开时间、标题模式、owner、文件类型等）只能作为候选筛选依据，不能升级为删除确认。执行 `drive +delete` 时必须使用解析后的 `--file-token` 和 `--type`。
 
 ## 命令
 

skills/lark-drive/references/lark-drive-files-list.md

@@ -41,12 +41,37 @@ lark-cli drive files list \
 
 也可以省略 `folder_token` 字段来请求根目录，但在 Agent 编排中建议显式传空字符串，避免把“忘记传参数”和“确认请求根目录”混在一起。
 
+## 按时间排序
+
+默认不要传 `order_by` / `direction`；服务端会按默认顺序返回。只有用户明确要求按创建时间或编辑时间排序时，才使用服务端排序参数。
+
+按创建时间升序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"CreatedTime","direction":"ASC","page_size":200}' \
+  --format json
+```
+
+按编辑时间降序列出当前文件夹直接子项：
+
+```bash
+lark-cli drive files list \
+  --params '{"folder_token":"<folder_token>","order_by":"EditedTime","direction":"DESC","page_size":200}' \
+  --format json
+```
+
+以上示例返回排序后的当前页；如果返回 `has_more=true`，保持相同 `folder_token` / `order_by` / `direction` / `page_size`，把 `next_page_token` 放入 `page_token` 继续翻页。
+
 ## 参数规则
 
 1. `folder_token` 必须放在 `--params` JSON 里；不要使用不存在的 `--folder-token` flag。
 2. `page_token` 必须放在 `--params` JSON 里；不要依赖 shell 变量拼接不完整的 JSON。
-3. `page_size` 建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
-4. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
+3. 默认不要传 `order_by` / `direction`；只有用户明确要求按创建时间 / 编辑时间排序时才使用服务端排序参数。
+4. 排序参数映射：创建时间 -> `order_by:"CreatedTime"`；编辑时间 / 修改时间 -> `order_by:"EditedTime"`；升序 -> `direction:"ASC"`；降序 -> `direction:"DESC"`。不要省略排序参数后再用 Python / shell 客户端排序替代。
+5. 排序查询建议带 `page_size:200` 减少翻页；只有用户要求完整分页、递归盘点、大目录全量导出，或当前页返回 `has_more=true` 后继续翻页时，才加入 `page_token`。
+6. `page_size` 在分页、递归盘点或全量导出时建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
+7. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
 
 ## 返回结构与解析
 

skills/lark-drive/references/lark-drive-inspect.md

@@ -47,4 +47,6 @@ JSON 输出包含以下字段：
 - `--url` 为必填参数
 - 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
 - wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
+- `+inspect` 只用于识别/消歧；如果任务已能通过 URL 路径形态完成路由判断，不必把它作为所有 Drive 操作的通用前置步骤
+- `+inspect` 失败后不要自动切到写接口继续尝试，先按错误提示处理权限、scope 或链接问题
 - 支持 `--dry-run` 查看将调用的 API 步骤

skills/lark-drive/references/lark-drive-permission-guide.md

@@ -10,6 +10,18 @@
 
 如果用户只是想向文档 owner 申请访问权限，优先使用 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)。
 
+## 公开权限修改前门槛
+
+公开权限修改是高风险写操作。执行 `drive permission.public patch --yes` 前同时确认：
+
+| 条件 | 可执行信号 |
+|------|------------|
+| 具体目标 | 单个 URL/token，或用户确认过的资源列表 |
+| 公开范围 | 用户明确选择组织内/互联网、可读/可编辑等具体 `link_share_entity` 档位 |
+| 执行确认 | 用户在本轮确认按该目标和范围执行 |
+
+“开放一下”“共享给大家”“让大家能看”只表达目标状态，不包含具体公开范围。先列出可选范围并停止等待用户选择；公开档位必须来自用户选择，CLI 的 `--yes` 只表示已获得用户对该档位的执行确认。
+
 ## 公开权限错误码
 
 调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。

skills/lark-drive/references/lark-drive-push.md

@@ -143,6 +143,7 @@ lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
 | `permission_denied` | `1061004` / HTTP 403 | 当前身份无权操作目标资源 | 停止重试，检查目标文件夹权限、身份类型（user / bot）和资源可见性 |
 | `invalid_api_parameters` | `1061002` | API 参数被服务端拒绝 | 停止重试，检查 `--folder-token`、覆盖模式、`file_token`、文件名和上传参数；不要对同一参数组合批量重试 |
 | `parent_node_missing` | `1061044` | 上传 / 建目录使用的父文件夹不存在或当前身份不可见 | 停止重试，检查 `--folder-token` 是否仍存在、是否有权限、父目录是否在 push 过程中被删除；不要继续上传同一目录树 |
+| `parent_sibling_limit` | `1062507` | 目标父文件夹单层子节点数量超过上限 | 停止重试，清理目标目录、换一个 `--folder-token`，或把上传内容拆到多个子目录 |
 | `rate_limited` | `99991400` | 触发频控 | 停止当前批次，退避后再重试 |
 | `server_error` | `1061001` / `2200` | Drive 服务端异常 | 停止当前批次，稍后重试；保留 `log_id` 便于排查 |
 

skills/lark-mail/references/lark-mail-watch.md

@@ -47,7 +47,7 @@ lark-cli mail +watch --print-output-schema
 |------|------|------|
 | `--mailbox <id>` | `me` | 订阅目标邮箱 |
 | `--msg-format <mode>` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` |
-| `--format <mode>` | `table` | 输出样式：`table` / `json` / `data` |
+| `--format <mode>` | `data` | 输出样式：`json`（带 ok/data 信封的 NDJSON 流）/ `data`（裸 NDJSON 流） |
 | `--folder-ids <json-array>` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` |
 | `--folders <json-array>` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） |
 | `--label-ids <json-array>` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` |