feat(profile): distinguish saved default from effective identity

profile list / config show only report the saved default profile, not the
app/profile a specific invocation actually resolves to (especially under
--profile or LARKSUITE_CLI_PROFILE). Rename the misleading profile list
JSON field active -> default (it is the configured default, not the one in
effect), and point config show / profile list / profile help at
lark-cli whoami --json for the identity actually used now. Restructure the
lark-shared skill profile guidance as an intent -> command table.

README.md

@@ -233,24 +233,6 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # Comma-separated values
 ```
 
-### JSON Output Contract
-
-With `--format json` (the default), success and error envelopes are distinct.
-
-Success goes to **stdout**, exit code `0`:
-
-```json
-{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
-```
-
-Errors go to **stderr**, non-zero exit code:
-
-```json
-{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
-```
-
-To check whether a command succeeded, test `ok == true` (or the exit code) — **not** `code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
-
 ### Pagination
 
 ```bash

README.zh.md

@@ -234,24 +234,6 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # 逗号分隔值
 ```
 
-### JSON 输出契约
-
-`--format json`（默认）下，成功与错误的信封结构不同。
-
-成功信封写入 **stdout**，退出码 0：
-
-```json
-{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
-```
-
-错误信封写入 **stderr**，退出码非 0：
-
-```json
-{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
-```
-
-判断命令是否成功，请检查 `ok == true`（或进程退出码），**不要用 `code == 0`**。与原始 OpenAPI 响应（`{"code": 0, "msg": "ok", ...}`）不同，成功信封没有 `code` 和 `msg` 字段；`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md)。
-
 ### 分页
 
 ```bash

cmd/auth/status.go

@@ -27,6 +27,9 @@ func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobr
 	cmd := &cobra.Command{
 		Use:   "status",
 		Short: "View current auth status",
+		Long: `Show OAuth user login, token validity, and granted scopes.
+For token-validity checks, run lark-cli auth status --json --verify.
+This is not profile/app selection diagnostics; use lark-cli whoami for the effective app/profile identity used by an invocation.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if runF != nil {
 				return runF(opts)

cmd/auth/status_test.go

@@ -6,6 +6,7 @@ package auth
 import (
 	"encoding/json"
 	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -13,6 +14,20 @@ import (
 	"github.com/larksuite/cli/internal/httpmock"
 )
 
+func TestAuthStatusHelpDistinguishesFromWhoami(t *testing.T) {
+	cmd := NewCmdAuthStatus(nil, nil)
+	for _, want := range []string{
+		"OAuth user login",
+		"auth status --json --verify",
+		"not profile/app selection diagnostics",
+		"lark-cli whoami",
+	} {
+		if !strings.Contains(cmd.Long, want) {
+			t.Errorf("auth status --help Long missing %q; got:\n%s", want, cmd.Long)
+		}
+	}
+}
+
 func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,

cmd/bootstrap.go

@@ -6,8 +6,10 @@ package cmd
 import (
 	"errors"
 	"io"
+	"os"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/envvars"
 	"github.com/spf13/pflag"
 )
 
@@ -26,5 +28,13 @@ func BootstrapInvocationContext(args []string) (cmdutil.InvocationContext, error
 	if err := fs.Parse(args); err != nil && !errors.Is(err, pflag.ErrHelp) {
 		return cmdutil.InvocationContext{}, err
 	}
-	return cmdutil.InvocationContext{Profile: globals.Profile}, nil
+
+	profileFromFlag := globals.Profile != ""
+	if !profileFromFlag {
+		globals.Profile = os.Getenv(envvars.CliProfile)
+	}
+	return cmdutil.InvocationContext{
+		Profile:         globals.Profile,
+		ProfileFromFlag: profileFromFlag,
+	}, nil
 }

cmd/bootstrap_test.go

@@ -3,7 +3,11 @@
 
 package cmd
 
-import "testing"
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/envvars"
+)
 
 func TestBootstrapInvocationContext_ProfileFlag(t *testing.T) {
 	inv, err := BootstrapInvocationContext([]string{"--profile", "target", "auth", "status"})
@@ -70,3 +74,45 @@ func TestBootstrapInvocationContext_HelpWithProfile(t *testing.T) {
 		t.Fatalf("profile = %q, want %q", inv.Profile, "target")
 	}
 }
+
+func TestBootstrapProfileEnvFallback(t *testing.T) {
+	t.Run("flag wins over env", func(t *testing.T) {
+		t.Setenv(envvars.CliProfile, "tenant_env")
+		inv, err := BootstrapInvocationContext([]string{"--profile", "tenant_flag", "whoami"})
+		if err != nil {
+			t.Fatalf("unexpected err: %v", err)
+		}
+		if inv.Profile != "tenant_flag" {
+			t.Errorf("got %q, want tenant_flag", inv.Profile)
+		}
+		if !inv.ProfileFromFlag {
+			t.Errorf("ProfileFromFlag = false, want true")
+		}
+	})
+	t.Run("env used when flag absent", func(t *testing.T) {
+		t.Setenv(envvars.CliProfile, "tenant_env")
+		inv, err := BootstrapInvocationContext([]string{"whoami"})
+		if err != nil {
+			t.Fatalf("unexpected err: %v", err)
+		}
+		if inv.Profile != "tenant_env" {
+			t.Errorf("got %q, want tenant_env", inv.Profile)
+		}
+		if inv.ProfileFromFlag {
+			t.Errorf("ProfileFromFlag = true, want false")
+		}
+	})
+	t.Run("empty when neither set", func(t *testing.T) {
+		t.Setenv(envvars.CliProfile, "")
+		inv, err := BootstrapInvocationContext([]string{"whoami"})
+		if err != nil {
+			t.Fatalf("unexpected err: %v", err)
+		}
+		if inv.Profile != "" {
+			t.Errorf("got %q, want empty", inv.Profile)
+		}
+		if inv.ProfileFromFlag {
+			t.Errorf("ProfileFromFlag = true, want false")
+		}
+	})
+}

cmd/config/config_test.go

@@ -84,6 +84,16 @@ func TestConfigShowCmd_FlagParsing(t *testing.T) {
 	}
 }
 
+func TestConfigShowHelpClarifiesSavedConfig(t *testing.T) {
+	cmd := NewCmdConfigShow(nil, nil)
+	if !strings.Contains(cmd.Short, "saved config") {
+		t.Errorf("config show short = %q, want saved config", cmd.Short)
+	}
+	if !strings.Contains(cmd.Long, "lark-cli whoami --json") {
+		t.Errorf("config show help missing whoami route")
+	}
+}
+
 func TestConfigShowRun_NotConfiguredReturnsStructuredError(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 

cmd/config/show.go

@@ -27,7 +27,8 @@ func NewCmdConfigShow(f *cmdutil.Factory, runF func(*ConfigShowOptions) error) *
 
 	cmd := &cobra.Command{
 		Use:   "show",
-		Short: "Show current configuration",
+		Short: "Show saved config",
+		Long:  "Shows saved config. To see the app/profile lark-cli is using now, run `lark-cli whoami --json`.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if runF != nil {
 				return runF(opts)

cmd/profile/list.go

@@ -21,7 +21,7 @@ type profileListItem struct {
 	Name        string         `json:"name"`
 	AppID       string         `json:"appId"`
 	Brand       core.LarkBrand `json:"brand"`
-	Active      bool           `json:"active"`
+	Default     bool           `json:"default"`
 	User        string         `json:"user,omitempty"`
 	TokenStatus string         `json:"tokenStatus,omitempty"`
 }
@@ -30,7 +30,8 @@ type profileListItem struct {
 func NewCmdProfileList(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List all profiles",
+		Short: "List saved profiles",
+		Long:  "Lists saved profiles. To see the app/profile lark-cli is using now, run `lark-cli whoami --json`.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return profileListRun(f)
 		},
@@ -53,7 +54,7 @@ func profileListRun(f *cmdutil.Factory) error {
 		return nil
 	}
 
-	// Intentionally uses "" to show the persistent active profile, not the ephemeral --profile override.
+	// Intentionally uses "" to show the saved default profile, not the ephemeral --profile override.
 	currentApp := multi.CurrentAppConfig("")
 	currentName := ""
 	if currentApp != nil {
@@ -66,10 +67,10 @@ func profileListRun(f *cmdutil.Factory) error {
 		name := app.ProfileName()
 
 		item := profileListItem{
-			Name:   name,
-			AppID:  app.AppId,
-			Brand:  app.Brand,
-			Active: name == currentName,
+			Name:    name,
+			AppID:   app.AppId,
+			Brand:   app.Brand,
+			Default: name == currentName,
 		}
 
 		if len(app.Users) > 0 {

cmd/profile/profile.go

@@ -14,6 +14,15 @@ func NewCmdProfile(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "profile",
 		Short: "Manage configuration profiles",
+		Long: `Profiles are named app identities managed by lark-cli.
+
+Profile selection:
+  lark-cli whoami --json       Show the app/profile lark-cli is using now.
+  lark-cli auth status --json  Verify OAuth login and token state.
+  --profile <name>             Use a profile for this command only.
+  LARKSUITE_CLI_PROFILE        Use a profile for the current shell / agent session.
+  config show / profile list   Inspect saved config, not current usage.
+  unset LARKSUITE_CLI_PROFILE  Clear the session profile and fall back to direct app env or configured default.`,
 	}
 	cmdutil.DisableAuthCheck(cmd)
 	cmdutil.SetTips(cmd, []string{

cmd/profile/profile_test.go

@@ -306,14 +306,21 @@ func TestProfileListRun_OutputsProfiles(t *testing.T) {
 	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
 		t.Fatalf("Unmarshal() error = %v; output=%s", err, stdout.String())
 	}
+	raw := stdout.String()
+	if strings.Contains(raw, `"active"`) {
+		t.Fatalf("profile list output contains legacy active field: %s", raw)
+	}
+	if !strings.Contains(raw, `"default"`) {
+		t.Fatalf("profile list output missing default field: %s", raw)
+	}
 	if len(got) != 2 {
 		t.Fatalf("len(got) = %d, want 2", len(got))
 	}
-	if got[0].Name != "default" || !got[0].Active {
-		t.Fatalf("got[0] = %#v, want active default profile", got[0])
+	if got[0].Name != "default" || !got[0].Default {
+		t.Fatalf("got[0] = %#v, want configured default profile", got[0])
 	}
-	if got[1].Name != "target" || got[1].Active {
-		t.Fatalf("got[1] = %#v, want inactive target profile", got[1])
+	if got[1].Name != "target" || got[1].Default {
+		t.Fatalf("got[1] = %#v, want non-default target profile", got[1])
 	}
 }
 
@@ -627,6 +634,35 @@ func TestProfileRemoveRun_ValidationErrors(t *testing.T) {
 	})
 }
 
+// TestProfileHelpHasSelectionSection asserts `profile --help` documents the
+// per-invocation flag and session-scoped env var for selecting a profile, so
+// users and AI agents can find LARKSUITE_CLI_PROFILE without reading source.
+func TestProfileHelpHasSelectionSection(t *testing.T) {
+	cmd := NewCmdProfile(nil)
+	if !strings.Contains(cmd.Long, "Profile selection:") {
+		t.Errorf("profile --help missing Profile selection section")
+	}
+	if !strings.Contains(cmd.Long, "LARKSUITE_CLI_PROFILE") {
+		t.Errorf("profile --help missing LARKSUITE_CLI_PROFILE")
+	}
+	if !strings.Contains(cmd.Long, "lark-cli whoami --json") {
+		t.Errorf("profile --help missing whoami identity route")
+	}
+	if !strings.Contains(cmd.Long, "config show / profile list") {
+		t.Errorf("profile --help missing saved-config boundary")
+	}
+}
+
+func TestProfileListHelpClarifiesSavedProfiles(t *testing.T) {
+	cmd := NewCmdProfileList(nil)
+	if !strings.Contains(cmd.Short, "saved profiles") {
+		t.Errorf("profile list short = %q, want saved profiles", cmd.Short)
+	}
+	if !strings.Contains(cmd.Long, "lark-cli whoami --json") {
+		t.Errorf("profile list help missing whoami route")
+	}
+}
+
 func TestProfileListRun_InvalidConfigReturnsValidationError(t *testing.T) {
 	dir := setupProfileConfigDir(t)
 	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{invalid json"), 0600); err != nil {

cmd/whoami/whoami.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
 )
@@ -33,6 +34,15 @@ type whoamiResult struct {
 	TokenStatus    string         `json:"tokenStatus"`
 	OnBehalfOf     *delegatedUser `json:"onBehalfOf,omitempty"`
 	Hint           string         `json:"hint,omitempty"`
+
+	// CredentialSource, Explicit, and DirectCredentialEnv surface the cached
+	// credential.IdentitySelection computed during resolution (not re-inferred
+	// here). CredentialSource can be empty ("") on the non-env
+	// extension-provider path (e.g. sidecar mode), where no selection kind
+	// applies; this is a documented, valid state, not an error.
+	CredentialSource    string                         `json:"credentialSource"`
+	Explicit            bool                           `json:"explicit"`
+	DirectCredentialEnv credential.DirectCredentialEnv `json:"directCredentialEnv"`
 }
 
 // delegatedUser is the user a user-identity acts on behalf of.
@@ -58,6 +68,10 @@ func NewCmdWhoami(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "whoami",
 		Short: "Show the current effective identity, app, profile, and token status (JSON)",
+		Long: `Show the effective app identity used by this invocation. This is not OAuth login status;
+use ` + "`lark-cli auth status --json`" + ` for OAuth user/token state.
+The JSON output includes credentialSource, appId, brand, and whether direct app credential
+env is present and matches the selected profile.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return whoamiRun(cmd, opts)
 		},
@@ -97,7 +111,17 @@ func whoamiRun(cmd *cobra.Command, opts *Options) error {
 		f.ResolveStrictMode(ctx).ForcedIdentity(),
 	)
 	diag := identitydiag.Diagnose(ctx, f, cfg, false)
-	res := buildResult(cfg, as, source, diag)
+	// Read the cached selection computed during resolution; never re-infer it
+	// here. A resolution failure (e.g. under a non-env extension provider that
+	// doesn't populate a selection) degrades to the zero value rather than
+	// regressing whoami's own error/diagnostic path above.
+	var selection credential.IdentitySelection
+	if f.Credential != nil {
+		if sel, err := f.Credential.Selection(ctx); err == nil {
+			selection = sel
+		}
+	}
+	res := buildResult(cfg, as, source, diag, selection)
 	output.PrintJson(f.IOStreams.Out, res)
 	return nil
 }
@@ -122,18 +146,23 @@ func resolveSource(changedAs bool, flagAs core.Identity, autoDetected bool, stri
 
 // buildResult maps the resolved identity and local diagnostics into the output.
 // ResolveAs only ever returns user or bot, so the default branch handles user.
-func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result) *whoamiResult {
+// selection is the cached credential.IdentitySelection from resolution; it is
+// read as-is, never recomputed.
+func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result, selection credential.IdentitySelection) *whoamiResult {
 	defaultAs := cfg.DefaultAs
 	if defaultAs == "" {
 		defaultAs = core.AsAuto
 	}
 	res := &whoamiResult{
-		Profile:        cfg.ProfileName,
-		AppID:          cfg.AppID,
-		Brand:          cfg.Brand,
-		DefaultAs:      string(defaultAs),
-		Identity:       string(as),
-		IdentitySource: source,
+		Profile:             cfg.ProfileName,
+		AppID:               cfg.AppID,
+		Brand:               cfg.Brand,
+		DefaultAs:           string(defaultAs),
+		Identity:            string(as),
+		IdentitySource:      source,
+		CredentialSource:    string(selection.Source),
+		Explicit:            selection.Explicit(),
+		DirectCredentialEnv: selection.DirectCredentialEnv,
 	}
 	// Use the diagnosed hint as-is: it is tailored to the credential source, so
 	// it never says "auth login" when that is blocked under an external provider.

cmd/whoami/whoami_test.go

@@ -15,10 +15,13 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
+	envprovider "github.com/larksuite/cli/extension/credential/env"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/envvars"
 	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/keychain"
 )
 
 func TestResolveSource(t *testing.T) {
@@ -52,7 +55,7 @@ func TestBuildResult_UserValid(t *testing.T) {
 	diag := identitydiag.Result{
 		User: identitydiag.Identity{Available: true, Status: "ready", TokenStatus: "valid", OpenID: "ou_x", UserName: "Alice"},
 	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag, credential.IdentitySelection{})
 
 	if r.Identity != "user" || r.IdentitySource != "auto_detect" {
 		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
@@ -77,7 +80,7 @@ func TestBuildResult_UserMissingToken(t *testing.T) {
 	diag := identitydiag.Result{
 		User: identitydiag.Identity{Available: false, Status: "missing", Hint: "run: lark-cli auth login --help"}, // never logged in
 	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
+	r := buildResult(cfg, core.AsUser, "auto_detect", diag, credential.IdentitySelection{})
 
 	if r.Available {
 		t.Fatalf("available = true, want false")
@@ -100,7 +103,7 @@ func TestBuildResult_BotReady(t *testing.T) {
 	diag := identitydiag.Result{
 		Bot: identitydiag.Identity{Available: true, Status: "ready"},
 	}
-	r := buildResult(cfg, core.AsBot, "default_as", diag)
+	r := buildResult(cfg, core.AsBot, "default_as", diag, credential.IdentitySelection{})
 
 	if r.Identity != "bot" || r.IdentitySource != "default_as" {
 		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
@@ -121,7 +124,7 @@ func TestBuildResult_BotNotConfigured(t *testing.T) {
 	diag := identitydiag.Result{
 		Bot: identitydiag.Identity{Available: false, Status: "not_configured", Hint: "run: lark-cli config --help"},
 	}
-	r := buildResult(cfg, core.AsBot, "auto_detect", diag)
+	r := buildResult(cfg, core.AsBot, "auto_detect", diag, credential.IdentitySelection{})
 
 	if r.Available {
 		t.Fatalf("available = true, want false")
@@ -318,3 +321,94 @@ func TestWhoami_ExternalProvider_UserHintNotKeychain(t *testing.T) {
 		t.Fatalf("hint should explain external management: %q", got.Hint)
 	}
 }
+
+// noopWhoamiKeychain is a no-op KeychainAccess; the profile below uses a
+// plaintext secret, so no keychain lookup is actually required.
+type noopWhoamiKeychain struct{}
+
+func (noopWhoamiKeychain) Get(service, account string) (string, error) { return "", nil }
+func (noopWhoamiKeychain) Set(service, account, value string) error    { return nil }
+func (noopWhoamiKeychain) Remove(service, account string) error        { return nil }
+
+// credentialSourceSecret is the profile secret written to config for
+// TestWhoamiIncludesCredentialSource. It must never leak into whoami's output
+// (security §5.1).
+const credentialSourceSecret = "test-secret"
+
+// profileSelectionFactory builds a Factory whose CredentialProvider resolves
+// an explicit profile ("tenant_a") supplied via the LARKSUITE_CLI_PROFILE env
+// fallback (not --profile), so Selection().Source resolves to
+// env:LARKSUITE_CLI_PROFILE and Explicit() is true, with no direct
+// app-credential env vars present.
+func profileSelectionFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer) {
+	t.Helper()
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	multi := &core.MultiAppConfig{
+		CurrentApp: "tenant_a",
+		Apps: []core.AppConfig{{
+			Name:      "tenant_a",
+			AppId:     "cli_a",
+			AppSecret: core.PlainSecret(credentialSourceSecret),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig: %v", err)
+	}
+
+	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return noopWhoamiKeychain{} }, "tenant_a")
+	cred := credential.NewCredentialProvider([]extcred.Provider{&envprovider.Provider{}}, defaultAcct, nil, nil)
+	cred.WithProfile("tenant_a", false) // fromFlag=false -> env:LARKSUITE_CLI_PROFILE
+
+	cfg := &core.CliConfig{ProfileName: "tenant_a", AppID: "cli_a", AppSecret: credentialSourceSecret, Brand: core.BrandFeishu}
+	out := &bytes.Buffer{}
+	f := &cmdutil.Factory{
+		Config:     func() (*core.CliConfig, error) { return cfg, nil },
+		Credential: cred,
+		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
+	}
+	return f, out
+}
+
+// TestWhoamiIncludesCredentialSource locks in the diagnostic fields surfaced
+// from the cached credential.IdentitySelection (Task 6): credentialSource,
+// explicit, and directCredentialEnv. whoami must read the cached selection
+// as-is, not re-infer it.
+func TestWhoamiIncludesCredentialSource(t *testing.T) {
+	f, out := profileSelectionFactory(t)
+
+	cmd := NewCmdWhoami(f)
+	cmd.SetArgs([]string{})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+
+	raw := out.String()
+	if strings.Contains(raw, credentialSourceSecret) {
+		t.Fatalf("whoami output leaked the profile secret: %s", raw)
+	}
+
+	var got whoamiResult
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\n%s", err, raw)
+	}
+	if got.CredentialSource != string(credential.SourceEnvProfile) {
+		t.Fatalf("credentialSource = %q, want %q", got.CredentialSource, credential.SourceEnvProfile)
+	}
+	if !got.Explicit {
+		t.Fatalf("explicit = false, want true")
+	}
+	if got.DirectCredentialEnv.Present {
+		t.Fatalf("directCredentialEnv.present = true, want false: %#v", got.DirectCredentialEnv)
+	}
+	if !strings.Contains(raw, `"credentialSource": "env:LARKSUITE_CLI_PROFILE"`) {
+		t.Fatalf("raw JSON missing credentialSource literal: %s", raw)
+	}
+	if got.DirectCredentialEnv.Present || len(got.DirectCredentialEnv.Keys) != 0 ||
+		got.DirectCredentialEnv.AppID != "" || got.DirectCredentialEnv.Matched || got.DirectCredentialEnv.ConflictsWithProfile {
+		t.Fatalf("directCredentialEnv = %#v, want only present:false set", got.DirectCredentialEnv)
+	}
+}

errs/ERROR_CONTRACT.md

@@ -72,28 +72,6 @@ other category. `error.type` is `"policy"`, `error.subtype` is one of
 `challenge_required` / `access_denied`, and process exit is `6` via
 `CategoryPolicy`.
 
-### Success envelope (stdout)
-
-For contrast: success responses render to **stdout** as an
-`output.Envelope` (`internal/output/envelope.go`), exit code `0`:
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": { "guid": "e297d3d0-..." },
-  "meta": { "count": 1 }
-}
-```
-
-Consumers must branch on `ok` (or the process exit code). The success
-envelope has **no top-level `code` or `msg` field** — `code` exists only
-inside `error`, where it is the upstream numeric code (invariant 4).
-Wrappers that follow the raw OpenAPI convention and test `code == 0`
-will misclassify every successful call as a failure, which is
-especially dangerous around write commands (e.g. retrying a create that
-already succeeded).
-
 ## Categories
 
 | Category | When | Exit | Typed struct |

errs/marshal_test.go

@@ -136,6 +136,77 @@ func TestConfigError_MarshalJSON(t *testing.T) {
 	}
 }
 
+func TestConfigError_ProfileFieldsMarshalJSON(t *testing.T) {
+	ce := NewConfigError(SubtypeAppCredentialIncomplete, "incomplete").
+		WithMissingKeys("LARKSUITE_CLI_APP_ID", "LARKSUITE_CLI_APP_SECRET").
+		WithProfile("work").
+		WithAppID("cli_abc").
+		WithCredentialSource("flag:--profile")
+	b, err := json.Marshal(ce)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	for _, want := range []string{
+		`"type":"config"`,
+		`"subtype":"app_credential_incomplete"`,
+		`"missing_keys":["LARKSUITE_CLI_APP_ID","LARKSUITE_CLI_APP_SECRET"]`,
+		`"profile":"work"`,
+		`"app_id":"cli_abc"`,
+		`"credential_source":"flag:--profile"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+
+	// omitempty: unset fields must not appear on the wire.
+	empty := NewConfigError(SubtypeProfileNotFound, "x")
+	b2, err := json.Marshal(empty)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s2 := string(b2)
+	for _, notWant := range []string{`"missing_keys"`, `"profile"`, `"app_id"`, `"credential_source"`} {
+		if strings.Contains(s2, notWant) {
+			t.Errorf("%q should be omitted when empty; got %s", notWant, s2)
+		}
+	}
+}
+
+func TestValidationError_ProfileConflictMarshalJSON(t *testing.T) {
+	ve := NewValidationError(SubtypeProfileAppCredentialConflict, "conflict").
+		WithProfileAppConflict("cli_profile", "cli_env")
+	b, err := json.Marshal(ve)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := string(b)
+	for _, want := range []string{
+		`"type":"validation"`,
+		`"subtype":"profile_app_credential_conflict"`,
+		`"profile_app_id":"cli_profile"`,
+		`"env_app_id":"cli_env"`,
+	} {
+		if !strings.Contains(s, want) {
+			t.Errorf("missing %q in %s", want, s)
+		}
+	}
+
+	// omitempty: unset conflict fields must not appear on the wire.
+	empty := NewValidationError(SubtypeInvalidArgument, "x")
+	b2, err := json.Marshal(empty)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s2 := string(b2)
+	for _, notWant := range []string{`"profile_app_id"`, `"env_app_id"`} {
+		if strings.Contains(s2, notWant) {
+			t.Errorf("%q should be omitted when empty; got %s", notWant, s2)
+		}
+	}
+}
+
 func TestNetworkError_MarshalJSON(t *testing.T) {
 	ne := &NetworkError{
 		Problem: Problem{Category: CategoryNetwork, Subtype: SubtypeNetworkTimeout, Message: "dial timeout"},

errs/subtypes.go

@@ -12,8 +12,9 @@ const (
 
 // CategoryValidation subtypes
 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)
+	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)
+	SubtypeProfileAppCredentialConflict Subtype = "profile_app_credential_conflict" // profile and direct app env both set but app_id differs
 )
 
 // CategoryAuthentication subtypes
@@ -41,9 +42,13 @@ const (
 
 // CategoryConfig subtypes
 const (
-	SubtypeInvalidClient Subtype = "invalid_client" // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
-	SubtypeNotConfigured Subtype = "not_configured" // local config file absent (user has not run `config init`)
-	SubtypeInvalidConfig Subtype = "invalid_config" // local config file present but malformed
+	SubtypeInvalidClient           Subtype = "invalid_client"            // app_id / app_secret incorrect (RFC 6749 §5.2 alignment)
+	SubtypeNotConfigured           Subtype = "not_configured"            // local config file absent (user has not run `config init`)
+	SubtypeInvalidConfig           Subtype = "invalid_config"            // local config file present but malformed
+	SubtypeProfileNotFound         Subtype = "profile_not_found"         // --profile / LARKSUITE_CLI_PROFILE points to a nonexistent profile
+	SubtypeNoActiveProfile         Subtype = "no_active_profile"         // no active identity input and no usable default profile
+	SubtypeAppCredentialIncomplete Subtype = "app_credential_incomplete" // direct app env missing app_id or app_secret
+	SubtypeProfileSecretInvalid    Subtype = "profile_secret_invalid"    // profile exists but its secret cannot be resolved locally
 )
 
 // CategoryNetwork subtypes

errs/types.go

@@ -61,9 +61,11 @@ type TypedError interface {
 // it is intentionally not serialized.
 type ValidationError struct {
 	Problem
-	Param  string         `json:"param,omitempty"`
-	Params []InvalidParam `json:"params,omitempty"`
-	Cause  error          `json:"-"`
+	Param        string         `json:"param,omitempty"`
+	Params       []InvalidParam `json:"params,omitempty"`
+	ProfileAppID string         `json:"profile_app_id,omitempty"`
+	EnvAppID     string         `json:"env_app_id,omitempty"`
+	Cause        error          `json:"-"`
 }
 
 // InvalidParam is one structured validation diagnostic: the parameter that
@@ -150,6 +152,12 @@ func (e *ValidationError) WithCause(cause error) *ValidationError {
 	return e
 }
 
+func (e *ValidationError) WithProfileAppConflict(profileAppID, envAppID string) *ValidationError {
+	e.ProfileAppID = profileAppID
+	e.EnvAppID = envAppID
+	return e
+}
+
 // =========================== AuthenticationError =============================
 
 // AuthenticationError is the typed error for CategoryAuthentication.
@@ -315,8 +323,17 @@ func (e *PermissionError) WithCause(cause error) *PermissionError {
 // intentionally not serialized.
 type ConfigError struct {
 	Problem
-	Field string `json:"field,omitempty"`
-	Cause error  `json:"-"`
+	Field       string   `json:"field,omitempty"`
+	MissingKeys []string `json:"missing_keys,omitempty"`
+	Profile     string   `json:"profile,omitempty"`
+	AppID       string   `json:"app_id,omitempty"`
+	// CredentialSource is the machine-readable App/credential selection source
+	// that produced this config error (e.g. "flag:--profile",
+	// "env:LARKSUITE_CLI_PROFILE", "config"). It is required on
+	// profile_not_found and no_active_profile (spec §5) so an agent can branch
+	// on how the identity was (or was not) chosen. It is never a secret.
+	CredentialSource string `json:"credential_source,omitempty"`
+	Cause            error  `json:"-"`
 }
 
 // Unwrap is nil-receiver safe; see ValidationError.Unwrap.
@@ -370,6 +387,29 @@ func (e *ConfigError) WithField(field string) *ConfigError {
 	return e
 }
 
+func (e *ConfigError) WithMissingKeys(keys ...string) *ConfigError {
+	e.MissingKeys = slices.Clone(keys)
+	return e
+}
+
+func (e *ConfigError) WithProfile(name string) *ConfigError {
+	e.Profile = name
+	return e
+}
+
+func (e *ConfigError) WithAppID(appID string) *ConfigError {
+	e.AppID = appID
+	return e
+}
+
+// WithCredentialSource records the machine-readable credential-selection source
+// on the wire (snake_case credential_source). The value is an enum string
+// (e.g. "flag:--profile", "config"), never a secret.
+func (e *ConfigError) WithCredentialSource(source string) *ConfigError {
+	e.CredentialSource = source
+	return e
+}
+
 func (e *ConfigError) WithCause(cause error) *ConfigError {
 	e.Cause = cause
 	return e

errs/types_test.go

@@ -643,3 +643,29 @@ func TestBuilderSetter_DefensiveCopy(t *testing.T) {
 		}
 	})
 }
+
+// ======================= Profile selection error subtypes =======================
+
+func TestConfigErrorProfileFields(t *testing.T) {
+	e := errs.NewConfigError(errs.SubtypeAppCredentialIncomplete, "incomplete").
+		WithMissingKeys("LARKSUITE_CLI_APP_ID").
+		WithCredentialSource("env:LARKSUITE_CLI_PROFILE")
+	p, ok := errs.ProblemOf(e)
+	if !ok || p.Subtype != errs.SubtypeAppCredentialIncomplete {
+		t.Fatalf("subtype mismatch: %+v", p)
+	}
+	if len(e.MissingKeys) != 1 || e.MissingKeys[0] != "LARKSUITE_CLI_APP_ID" {
+		t.Errorf("missing_keys not set: %v", e.MissingKeys)
+	}
+	if e.CredentialSource != "env:LARKSUITE_CLI_PROFILE" {
+		t.Errorf("credential_source not set: %q", e.CredentialSource)
+	}
+}
+
+func TestValidationErrorProfileConflict(t *testing.T) {
+	e := errs.NewValidationError(errs.SubtypeProfileAppCredentialConflict, "conflict").
+		WithProfileAppConflict("cli_profile", "cli_env")
+	if e.ProfileAppID != "cli_profile" || e.EnvAppID != "cli_env" {
+		t.Errorf("conflict fields not set: %q %q", e.ProfileAppID, e.EnvAppID)
+	}
+}

internal/cmdutil/factory.go

@@ -27,6 +27,11 @@ import (
 // In tests, replace any field to stub out external dependencies.
 type InvocationContext struct {
 	Profile string
+	// ProfileFromFlag is true when Profile was set via the --profile flag,
+	// and false when it came from the LARKSUITE_CLI_PROFILE env fallback
+	// (or neither was set). Downstream credential resolution uses this to
+	// report the correct profile source.
+	ProfileFromFlag bool
 }
 
 type Factory struct {

internal/cmdutil/factory_default.go

@@ -61,10 +61,11 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 	// Phase 2: Credential (sole data source)
 	// Keychain is read via closure so callers can replace f.Keychain after construction.
 	f.Credential = buildCredentialProvider(credentialDeps{
-		Keychain:   func() keychain.KeychainAccess { return f.Keychain },
-		Profile:    inv.Profile,
-		HttpClient: f.HttpClient,
-		ErrOut:     f.IOStreams.ErrOut,
+		Keychain:        func() keychain.KeychainAccess { return f.Keychain },
+		Profile:         inv.Profile,
+		ProfileFromFlag: inv.ProfileFromFlag,
+		HttpClient:      f.HttpClient,
+		ErrOut:          f.IOStreams.ErrOut,
 	})
 
 	// Phase 3: Config derived from Credential via an explicit conversion boundary.
@@ -162,10 +163,11 @@ func buildSDKTransport() http.RoundTripper {
 }
 
 type credentialDeps struct {
-	Keychain   func() keychain.KeychainAccess
-	Profile    string
-	HttpClient func() (*http.Client, error)
-	ErrOut     io.Writer
+	Keychain        func() keychain.KeychainAccess
+	Profile         string
+	ProfileFromFlag bool
+	HttpClient      func() (*http.Client, error)
+	ErrOut          io.Writer
 }
 
 func buildCredentialProvider(deps credentialDeps) *credential.CredentialProvider {
@@ -178,5 +180,6 @@ func buildCredentialProvider(deps credentialDeps) *credential.CredentialProvider
 	// depend on. enrichUserInfo failures are already non-fatal (the
 	// provider clears unverified identity fields), so silencing the
 	// warning is safe.
-	return credential.NewCredentialProvider(providers, defaultAcct, defaultToken, deps.HttpClient)
+	return credential.NewCredentialProvider(providers, defaultAcct, defaultToken, deps.HttpClient).
+		WithProfile(deps.Profile, deps.ProfileFromFlag)
 }

internal/credential/credential_provider.go

@@ -9,13 +9,21 @@ import (
 	"fmt"
 	"io"
 	"net/http"
+	"os"
 	"sync"
 
+	"github.com/larksuite/cli/errs"
 	extcred "github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/envvars"
 )
 
+// directCredentialProviderName is the Name() of the env provider, the source
+// of direct app credentials (LARKSUITE_CLI_APP_ID / _APP_SECRET). Only its
+// incomplete blocks map to app_credential_incomplete (spec §3 step 1).
+const directCredentialProviderName = "env"
+
 // DefaultAccountResolver is implemented by the default account provider.
 type DefaultAccountResolver interface {
 	ResolveAccount(ctx context.Context) (*Account, error)
@@ -136,10 +144,18 @@ type CredentialProvider struct {
 	httpClient   func() (*http.Client, error)
 	warnOut      io.Writer
 
+	// profile is the active profile (from --profile or LARKSUITE_CLI_PROFILE).
+	// profileFromFlag discriminates the source for the reported selection.
+	profile         string
+	profileFromFlag bool
+
 	accountOnce    sync.Once
 	account        *Account
 	accountErr     error
 	selectedSource credentialSource
+	// selection is the explainable credential-selection result, populated by
+	// doResolveAccount under accountOnce. It never carries a secret (§5.1).
+	selection IdentitySelection
 
 	hintOnce sync.Once
 	hint     *IdentityHint
@@ -161,6 +177,15 @@ func (p *CredentialProvider) SetWarnOut(warnOut io.Writer) *CredentialProvider {
 	return p
 }
 
+// WithProfile records the active profile and whether it came from the
+// --profile flag (as opposed to the LARKSUITE_CLI_PROFILE env fallback).
+// It governs credential arbitration and the reported selection source.
+func (p *CredentialProvider) WithProfile(profile string, fromFlag bool) *CredentialProvider {
+	p.profile = profile
+	p.profileFromFlag = fromFlag
+	return p
+}
+
 // ResolveAccount resolves app credentials. Result is cached after first call.
 // NOTE: Uses sync.Once — only the context from the first call is used for resolution.
 // Subsequent calls return the cached result regardless of their context.
@@ -172,40 +197,273 @@ func (p *CredentialProvider) ResolveAccount(ctx context.Context) (*Account, erro
 	return p.account, p.accountErr
 }
 
+// doResolveAccount arbitrates the credential/App selection per the spec
+// resolution order (§3): env-partial → profile → env-complete → config default.
+// It populates p.selection (no secret; §5.1) and p.selectedSource on every
+// success path.
 func (p *CredentialProvider) doResolveAccount(ctx context.Context) (*Account, error) {
+	// Step 1 (spec §3): consult the extension providers. The env provider is
+	// the "direct app credential" source. An incomplete direct credential
+	// (only APP_ID or only APP_SECRET set) short-circuits to
+	// app_credential_incomplete regardless of the active profile.
+	var envAcct *Account
+	var envSource extensionTokenSource
 	for _, prov := range p.providers {
 		acct, err := prov.ResolveAccount(ctx)
 		if err != nil {
+			var blockErr *extcred.BlockError
+			// Only the env (direct-credential) provider maps an incomplete
+			// block to app_credential_incomplete. Other providers' blocks
+			// propagate unchanged so they still stop the chain (§3 step 1
+			// is specifically about direct app credential env vars).
+			if errors.As(err, &blockErr) && prov.Name() == directCredentialProviderName {
+				if missing := missingDirectCredentialKeys(); len(missing) > 0 {
+					return nil, errs.NewConfigError(errs.SubtypeAppCredentialIncomplete,
+						"direct app credential is incomplete").
+						WithMissingKeys(missing...).
+						WithHint("set both %s and %s, or unset both and use --profile / a config default.",
+							envvars.CliAppID, envvars.CliAppSecret)
+				}
+				// Block for a reason other than incompleteness (e.g. an
+				// invalid identity/strict-mode value); preserve prior behavior.
+				return nil, err
+			}
 			return nil, err
 		}
 		if acct != nil {
-			internal := convertAccount(acct)
-			source := extensionTokenSource{provider: prov}
-			if err := p.enrichUserInfo(ctx, internal, source); err != nil {
-				if p.warnOut != nil {
-					_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", source.Name(), err)
+			// Only the env (direct-credential) provider feeds profile
+			// arbitration / conflict detection / DirectCredentialEnv reporting.
+			// This mirrors the block-path guard above. A non-env extension
+			// provider (e.g. sidecar) is NOT a direct-credential env account:
+			// it wins outright here, returning its account + token source
+			// unchanged (pre-diff behavior), without being misreported as a
+			// direct env credential (§4.2: Present = direct env vars actually
+			// set) or triggering a spurious profile_app_credential_conflict.
+			if prov.Name() != directCredentialProviderName {
+				internal := convertAccount(acct)
+				source := extensionTokenSource{provider: prov}
+				if err := p.enrichUserInfo(ctx, internal, source); err != nil {
+					if p.warnOut != nil {
+						_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", source.Name(), err)
+					}
+					// enrichUserInfo failure is non-fatal: SupportedIdentities
+					// (used for strict mode) is already set by the provider.
+					// Clear unverified user identity for safety.
+					internal.UserOpenId = ""
+					internal.UserName = ""
 				}
-				// enrichUserInfo failure is non-fatal: SupportedIdentities
-				// (used for strict mode) is already set by the provider.
-				// Clear unverified user identity for safety.
-				internal.UserOpenId = ""
-				internal.UserName = ""
+				p.selectedSource = source
+				return internal, nil
 			}
-			p.selectedSource = source
-			return internal, nil
+			envAcct = convertAccount(acct)
+			envSource = extensionTokenSource{provider: prov}
+			break
 		}
 	}
-	if p.defaultAcct != nil {
+
+	// Step 2 (spec §3): an explicit profile was requested.
+	if p.profile != "" {
+		multi, loadErr := core.LoadMultiAppConfig()
+		if errors.Is(loadErr, core.ErrMalformedConfig) {
+			// A malformed config must not be masked as profile_not_found (which
+			// would tell the user to run `profile list` and hide a real config
+			// problem). Pass the underlying error through unchanged so
+			// errors.Is / errors.Unwrap keep working. An absent config is not
+			// malformed and still falls through to the friendly
+			// profile_not_found below, since the requested profile cannot exist.
+			return nil, loadErr
+		}
+		var app *core.AppConfig
+		if loadErr == nil && multi != nil {
+			app = multi.FindApp(p.profile)
+		}
+		if app == nil {
+			return nil, errs.NewConfigError(errs.SubtypeProfileNotFound,
+				"profile %q not found", p.profile).
+				WithProfile(p.profile).
+				WithCredentialSource(string(p.profileSource())).
+				WithHint("run `lark-cli profile list` to see available profiles.")
+		}
+		if envAcct != nil {
+			// E == complete: the direct env app_id must match the profile.
+			if app.AppId != envAcct.AppID {
+				return nil, errs.NewValidationError(errs.SubtypeProfileAppCredentialConflict,
+					"profile %q app_id does not match %s", p.profile, envvars.CliAppID).
+					WithProfileAppConflict(app.AppId, envAcct.AppID).
+					WithHint("unset %s/%s, or select a profile whose app_id matches the environment.",
+						envvars.CliAppID, envvars.CliAppSecret)
+			}
+			p.selection = IdentitySelection{
+				Source: p.profileSource(),
+				DirectCredentialEnv: DirectCredentialEnv{
+					Present: true,
+					Keys:    presentDirectCredentialKeys(),
+					AppID:   envAcct.AppID,
+					Matched: true,
+				},
+			}
+		} else {
+			p.selection = IdentitySelection{
+				Source:              p.profileSource(),
+				DirectCredentialEnv: DirectCredentialEnv{Present: false},
+			}
+		}
+		// Resolve the profile's own (keychain-backed) credential locally.
 		acct, err := p.defaultAcct.ResolveAccount(ctx)
 		if err != nil {
-			return nil, err
+			// SECURITY (§5.1): generic message — never embed the underlying
+			// error or any secret material.
+			p.selection = IdentitySelection{}
+			return nil, errs.NewConfigError(errs.SubtypeProfileSecretInvalid,
+				"profile %q credential could not be resolved locally", p.profile).
+				WithProfile(p.profile).
+				WithAppID(app.AppId).
+				WithHint("verify the profile's app secret or re-add the profile with `lark-cli config`.")
 		}
 		p.selectedSource = defaultTokenSource{resolver: p.defaultToken}
 		return acct, nil
 	}
+
+	// Step 3 (spec §3): no explicit profile — direct env credential wins.
+	if envAcct != nil {
+		if err := p.enrichUserInfo(ctx, envAcct, envSource); err != nil {
+			if p.warnOut != nil {
+				_, _ = fmt.Fprintf(p.warnOut, "warning: unable to verify user identity from credential source %q: %v\n", envSource.Name(), err)
+			}
+			// enrichUserInfo failure is non-fatal: SupportedIdentities
+			// (used for strict mode) is already set by the provider.
+			// Clear unverified user identity for safety.
+			envAcct.UserOpenId = ""
+			envAcct.UserName = ""
+		}
+		p.selectedSource = envSource
+		p.selection = IdentitySelection{
+			Source: SourceEnvAppID,
+			DirectCredentialEnv: DirectCredentialEnv{
+				Present: true,
+				Keys:    presentDirectCredentialKeys(),
+				AppID:   envAcct.AppID,
+			},
+		}
+		return envAcct, nil
+	}
+
+	// No direct env credential and no profile → the config default.
+	if p.defaultAcct != nil {
+		acct, err := p.defaultAcct.ResolveAccount(ctx)
+		if err != nil {
+			// The config default failed to resolve. Distinguish (spec §3 step
+			// 3.2): a default profile that EXISTS (has an app_id) but whose
+			// secret cannot be resolved locally is a profile_secret_invalid —
+			// "identity is configured, its secret is broken" is more actionable
+			// than "no active profile". Only when there is genuinely no usable
+			// default profile do we report no_active_profile. Other typed
+			// failures (e.g. a specific config error) pass through unchanged.
+			if prob, ok := errs.ProblemOf(err); ok && prob.Subtype == errs.SubtypeNotConfigured {
+				if name, appID, ok := defaultProfileIdentity(); ok {
+					// SECURITY (§5.1): generic message — never embed the
+					// underlying error or any secret material. app_id is
+					// plaintext and safe to echo.
+					return nil, errs.NewConfigError(errs.SubtypeProfileSecretInvalid,
+						"profile %q credential could not be resolved locally", name).
+						WithProfile(name).
+						WithAppID(appID).
+						WithHint("verify the profile's app secret or re-add the profile with `lark-cli config`.")
+				}
+				return nil, errs.NewConfigError(errs.SubtypeNoActiveProfile, "no active profile").
+					WithCredentialSource(noActiveProfileCredentialSource).
+					WithHint("run `lark-cli config init` / `lark-cli profile add`, or set %s.", envvars.CliProfile)
+			}
+			return nil, err
+		}
+		multi, _ := core.LoadMultiAppConfig()
+		p.selectedSource = defaultTokenSource{resolver: p.defaultToken}
+		p.selection = IdentitySelection{Source: selectionSourceForDefault(multi)}
+		return acct, nil
+	}
 	return nil, core.NotConfiguredError()
 }
 
+// profileSource reports the credential source kind for a profile-backed
+// selection, discriminating the --profile flag from the env fallback.
+func (p *CredentialProvider) profileSource() CredentialSourceKind {
+	if p.profileFromFlag {
+		return SourceFlagProfile
+	}
+	return SourceEnvProfile
+}
+
+// noActiveProfileCredentialSource is the credential_source reported on the
+// no_active_profile error. Spec §5 fixes this to the literal "config": there is
+// no resolved default profile at all, so the more specific config:currentApp /
+// config:firstApp source values (used on successful config-default selections)
+// would be misleading. It is an enum string, never a secret.
+const noActiveProfileCredentialSource = "config"
+
+// defaultProfileIdentity reports the config default profile's display name and
+// app_id when a usable default profile actually EXISTS (currentApp > firstApp
+// resolves to an app with a non-empty app_id). It never touches the keychain or
+// any secret, so it can distinguish "default profile exists but its secret is
+// broken" (→ profile_secret_invalid) from "no usable default profile at all"
+// (→ no_active_profile), without risking a secret leak (§5.1).
+func defaultProfileIdentity() (name, appID string, ok bool) {
+	multi, err := core.LoadMultiAppConfig()
+	if err != nil || multi == nil {
+		return "", "", false
+	}
+	app := multi.CurrentAppConfig("")
+	if app == nil || app.AppId == "" {
+		return "", "", false
+	}
+	return app.ProfileName(), app.AppId, true
+}
+
+// selectionSourceForDefault reports whether the config default resolved to the
+// explicit currentApp or fell back to the first app (spec §3 step 3.2).
+func selectionSourceForDefault(multi *core.MultiAppConfig) CredentialSourceKind {
+	if multi != nil && multi.CurrentApp != "" {
+		return SourceConfigCurrentApp
+	}
+	return SourceConfigFirstApp
+}
+
+// missingDirectCredentialKeys returns the NAMES (never values) of the direct
+// app credential env vars that are absent. Used only when the env provider
+// blocks, to map an incomplete direct credential to app_credential_incomplete.
+func missingDirectCredentialKeys() []string {
+	var missing []string
+	if os.Getenv(envvars.CliAppID) == "" {
+		missing = append(missing, envvars.CliAppID)
+	}
+	if os.Getenv(envvars.CliAppSecret) == "" {
+		missing = append(missing, envvars.CliAppSecret)
+	}
+	return missing
+}
+
+// presentDirectCredentialKeys returns the NAMES (never values) of the direct
+// app credential env vars that are set. Used to annotate DirectCredentialEnv.
+func presentDirectCredentialKeys() []string {
+	var keys []string
+	if os.Getenv(envvars.CliAppID) != "" {
+		keys = append(keys, envvars.CliAppID)
+	}
+	if os.Getenv(envvars.CliAppSecret) != "" {
+		keys = append(keys, envvars.CliAppSecret)
+	}
+	return keys
+}
+
+// Selection resolves the account (once) and returns the cached, secret-free
+// explanation of how the credential/App was selected. It mirrors
+// selectedCredentialSource: resolve-then-return.
+func (p *CredentialProvider) Selection(ctx context.Context) (IdentitySelection, error) {
+	if _, err := p.ResolveAccount(ctx); err != nil {
+		return IdentitySelection{}, err
+	}
+	return p.selection, nil
+}
+
 // enrichUserInfo resolves user identity when extension provides a UAT.
 // If UAT is available, user_info API call is mandatory (security: verify token validity).
 // If no UAT from extension, falls back to provider-supplied OpenID.

internal/credential/credential_provider_selection_test.go

@@ -0,0 +1,554 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package credential_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
+	envprovider "github.com/larksuite/cli/extension/credential/env"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/keychain"
+)
+
+func asConfigError(t *testing.T, err error) *errs.ConfigError {
+	t.Helper()
+	var ce *errs.ConfigError
+	if !errors.As(err, &ce) {
+		t.Fatalf("expected *errs.ConfigError, got %T: %v", err, err)
+	}
+	return ce
+}
+
+func asValidationError(t *testing.T, err error) *errs.ValidationError {
+	t.Helper()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	return ve
+}
+
+// secretValue is the profile secret written to config. It must NEVER appear in
+// any error message or IdentitySelection (security §5.1).
+const secretValue = "your-secret"
+
+// envSecretValue is the direct env app secret. Same no-leak guarantee.
+const envSecretValue = "your-password"
+
+// writeConfigTenantA writes a config with a single profile "tenant_a" (app_id
+// "cli_a"). The secret is a plaintext secret stored in config, which resolves
+// locally without a keychain lookup.
+func writeConfigTenantA(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	multi := &core.MultiAppConfig{
+		CurrentApp: "tenant_a",
+		Apps: []core.AppConfig{{
+			Name:      "tenant_a",
+			AppId:     "cli_a",
+			AppSecret: core.PlainSecret(secretValue),
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig: %v", err)
+	}
+}
+
+// writeConfigTenantABroken writes tenant_a with a keychain-backed secret ref
+// that cannot be resolved (noop keychain returns empty), so profile secret
+// resolution fails locally.
+func writeConfigTenantABroken(t *testing.T) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	// A keychain SecretRef whose key does NOT match app_id cli_a. Local secret
+	// resolution fails (ValidateSecretKeyMatch), exercising profile_secret_invalid.
+	multi := &core.MultiAppConfig{
+		CurrentApp: "tenant_a",
+		Apps: []core.AppConfig{{
+			Name:      "tenant_a",
+			AppId:     "cli_a",
+			AppSecret: core.SecretInput{Ref: &core.SecretRef{Source: "keychain", ID: "appsecret:wrong_key"}},
+			Brand:     core.BrandFeishu,
+		}},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig: %v", err)
+	}
+}
+
+func newProvider(t *testing.T, profile string, fromFlag bool) *credential.CredentialProvider {
+	t.Helper()
+	ep := &envprovider.Provider{}
+	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, profile)
+	cp := credential.NewCredentialProvider([]extcred.Provider{ep}, defaultAcct, nil, nil)
+	cp.WithProfile(profile, fromFlag)
+	return cp
+}
+
+// assertNoSecretLeak fails if any secret value appears in the given strings.
+func assertNoSecretLeak(t *testing.T, where string, vals ...string) {
+	t.Helper()
+	for _, v := range vals {
+		if v == "" {
+			continue
+		}
+		if strings.Contains(v, secretValue) {
+			t.Errorf("%s leaked profile secret: %q", where, v)
+		}
+		if strings.Contains(v, envSecretValue) {
+			t.Errorf("%s leaked env secret: %q", where, v)
+		}
+	}
+}
+
+func subtypeOf(t *testing.T, err error) errs.Subtype {
+	t.Helper()
+	if err == nil {
+		t.Fatalf("expected error, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error is not a typed problem: %v", err)
+	}
+	return p.Subtype
+}
+
+// State #2: P none, E none, C none -> no_active_profile.
+func TestSelection_State2_NoActiveProfile(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir()) // empty dir -> no config
+	cp := newProvider(t, "", false)
+
+	sel, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeNoActiveProfile {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeNoActiveProfile)
+	}
+	// Defect 1 (spec §5): no_active_profile must carry credential_source=config.
+	ce := asConfigError(t, err)
+	if ce.CredentialSource != "config" {
+		t.Errorf("credential_source = %q, want %q", ce.CredentialSource, "config")
+	}
+	assertNoSecretLeak(t, "state2", err.Error(), string(sel.Source))
+}
+
+// Config-default profile with a broken secret: P none, E none, C present but the
+// default profile's keychain secret ref is corrupted. Per spec §3 step 3.2 this
+// must be profile_secret_invalid (the identity IS configured, only its secret is
+// broken) — NOT no_active_profile (which is reserved for "no usable default").
+func TestSelection_ConfigDefaultBrokenSecret_ProfileSecretInvalid(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantABroken(t) // CurrentApp = tenant_a (app_id cli_a), broken keychain ref
+	cp := newProvider(t, "", false)
+
+	_, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
+	}
+	ce := asConfigError(t, err)
+	if ce.Profile != "tenant_a" {
+		t.Errorf("profile = %q, want tenant_a", ce.Profile)
+	}
+	if ce.AppID != "cli_a" {
+		t.Errorf("app_id = %q, want cli_a", ce.AppID)
+	}
+	// §5.1: generic message, no cause, no secret anywhere.
+	if errors.Unwrap(ce) != nil {
+		t.Errorf("profile_secret_invalid must not attach a cause, got %v", errors.Unwrap(ce))
+	}
+	assertNoSecretLeak(t, "config-default-broken", ce.Message, ce.Hint, ce.AppID)
+}
+
+// Explicit profile requested but the config file is malformed. The load error
+// must be propagated (errors.Is ErrMalformedConfig) rather than masked as
+// profile_not_found, which would hide a real config problem and misdirect the
+// user to `profile list`. An absent config is separately still profile_not_found.
+func TestSelection_ExplicitProfile_MalformedConfig_PropagatesError(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := os.MkdirAll(core.GetConfigDir(), 0o700); err != nil {
+		t.Fatalf("mkdir config dir: %v", err)
+	}
+	if err := os.WriteFile(core.GetConfigPath(), []byte("{ this is not valid json"), 0o600); err != nil {
+		t.Fatalf("write malformed config: %v", err)
+	}
+	cp := newProvider(t, "tenant_a", true)
+
+	_, err := cp.Selection(context.Background())
+	if err == nil {
+		t.Fatalf("expected error for malformed config, got nil")
+	}
+	if !errors.Is(err, core.ErrMalformedConfig) {
+		t.Fatalf("malformed config error not propagated: %v", err)
+	}
+	if prob, ok := errs.ProblemOf(err); ok && prob.Subtype == errs.SubtypeProfileNotFound {
+		t.Fatalf("malformed config masked as profile_not_found")
+	}
+}
+
+// State #3: P none, E partial (only APP_ID) -> app_credential_incomplete.
+func TestSelection_State3_EnvPartial(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "cli_env")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantA(t)
+	cp := newProvider(t, "", false)
+
+	_, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeAppCredentialIncomplete {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeAppCredentialIncomplete)
+	}
+	prob, _ := errs.ProblemOf(err)
+	ce := asConfigError(t, err)
+	if !slices.Contains(ce.MissingKeys, envvars.CliAppSecret) {
+		t.Errorf("missing_keys = %v, want to contain %q", ce.MissingKeys, envvars.CliAppSecret)
+	}
+	// missing_keys must be NAMES only, never values.
+	for _, k := range ce.MissingKeys {
+		if strings.Contains(k, envSecretValue) || strings.Contains(k, secretValue) {
+			t.Errorf("missing_keys contains a value, not a name: %q", k)
+		}
+	}
+	assertNoSecretLeak(t, "state3", prob.Message, prob.Hint)
+}
+
+// State #4: P none, E complete -> env:LARKSUITE_CLI_APP_ID.
+func TestSelection_State4_EnvComplete(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "cli_env")
+	t.Setenv(envvars.CliAppSecret, envSecretValue)
+	writeConfigTenantA(t)
+	cp := newProvider(t, "", false)
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if sel.Source != credential.SourceEnvAppID {
+		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceEnvAppID)
+	}
+	if !sel.DirectCredentialEnv.Present {
+		t.Errorf("DirectCredentialEnv.Present = false, want true")
+	}
+	assertNoSecretLeak(t, "state4", string(sel.Source), sel.DirectCredentialEnv.AppID)
+	assertNoSecretLeak(t, "state4-keys", sel.DirectCredentialEnv.Keys...)
+}
+
+// State #5: P valid, E none -> flag:--profile (fromFlag) source.
+func TestSelection_State5_ProfileOnly(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantA(t)
+	cp := newProvider(t, "tenant_a", true)
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if sel.Source != credential.SourceFlagProfile {
+		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceFlagProfile)
+	}
+	if sel.DirectCredentialEnv.Present {
+		t.Errorf("DirectCredentialEnv.Present = true, want false")
+	}
+	assertNoSecretLeak(t, "state5", string(sel.Source))
+}
+
+// State #5b: P valid from env (not flag) -> env:LARKSUITE_CLI_PROFILE source.
+func TestSelection_State5_ProfileFromEnv(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantA(t)
+	cp := newProvider(t, "tenant_a", false)
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if sel.Source != credential.SourceEnvProfile {
+		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceEnvProfile)
+	}
+}
+
+// State #6: P missing (nonexistent), E complete -> profile_not_found.
+func TestSelection_State6_ProfileNotFound(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "cli_env")
+	t.Setenv(envvars.CliAppSecret, envSecretValue)
+	writeConfigTenantA(t)
+	cp := newProvider(t, "does_not_exist", true)
+
+	sel, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeProfileNotFound {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileNotFound)
+	}
+	prob, _ := errs.ProblemOf(err)
+	// Defect 1 (spec §5): profile_not_found must carry the credential_source that
+	// named the profile — here the --profile flag.
+	ce := asConfigError(t, err)
+	if ce.CredentialSource != string(credential.SourceFlagProfile) {
+		t.Errorf("credential_source = %q, want %q", ce.CredentialSource, credential.SourceFlagProfile)
+	}
+	assertNoSecretLeak(t, "state6", err.Error(), prob.Hint, string(sel.Source))
+}
+
+// State #7: P valid but secret broken, E none -> profile_secret_invalid.
+func TestSelection_State7_ProfileSecretInvalid(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantABroken(t)
+	cp := newProvider(t, "tenant_a", true)
+
+	_, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
+	}
+	ce := asConfigError(t, err)
+	if ce.Profile != "tenant_a" {
+		t.Errorf("profile = %q, want tenant_a", ce.Profile)
+	}
+	if ce.AppID != "cli_a" {
+		t.Errorf("app_id = %q, want cli_a", ce.AppID)
+	}
+	assertNoSecretLeak(t, "state7", ce.Message, ce.Hint)
+}
+
+// secretMarkerValue is a distinctive string used to prove that the
+// profile_secret_invalid path drops the underlying error entirely, even when
+// that underlying error's own message CONTAINS a secret. Unlike
+// writeConfigTenantABroken (whose noop-keychain failure is a harmless empty
+// error), this uses a custom DefaultAccountResolver whose error text embeds
+// the marker, closing the gap where a leak could hide in a cause chain that
+// happens to be empty in the noop-keychain case.
+const secretMarkerValue = "your-access-token"
+
+// leakingSecretResolver is a DefaultAccountResolver stub whose ResolveAccount
+// fails with an error whose message contains secretMarkerValue, simulating a
+// real keychain/secret-resolution failure that echoes back sensitive material
+// (e.g. a keychain library including the attempted secret in its error text).
+type leakingSecretResolver struct{}
+
+func (leakingSecretResolver) ResolveAccount(ctx context.Context) (*credential.Account, error) {
+	return nil, fmt.Errorf("keychain decode failed for secret %s", secretMarkerValue)
+}
+
+// State #7 (secret-bearing underlying error): P valid, but the underlying
+// account/secret resolution fails with an error that itself contains a
+// secret. This locks the §5.1 design: doResolveAccount emits a generic
+// profile_secret_invalid ConfigError WITHOUT attaching the underlying cause,
+// so a secret embedded in that underlying error can never surface through
+// err.Error(), Message, Hint, the unwrapped cause chain, or Selection().
+func TestSelection_State7_UnderlyingErrorContainingSecret_NotLeaked(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantA(t) // profile "tenant_a" exists with app_id "cli_a"
+
+	ep := &envprovider.Provider{}
+	cp := credential.NewCredentialProvider([]extcred.Provider{ep}, leakingSecretResolver{}, nil, nil)
+	cp.WithProfile("tenant_a", true)
+
+	sel, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeProfileSecretInvalid {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileSecretInvalid)
+	}
+	ce := asConfigError(t, err)
+	if ce.Profile != "tenant_a" {
+		t.Errorf("profile = %q, want tenant_a", ce.Profile)
+	}
+	if ce.AppID != "cli_a" {
+		t.Errorf("app_id = %q, want cli_a", ce.AppID)
+	}
+
+	// Walk the full unwrap chain. This is the assertion that would catch a
+	// regression where the profile_secret_invalid branch starts attaching the
+	// underlying error via WithCause: if it did, this loop would find the
+	// marker in a wrapped link even though err.Error()/Message/Hint (which
+	// only reflect the top-level ConfigError, not the chain) might look clean.
+	for cur := error(ce); cur != nil; cur = errors.Unwrap(cur) {
+		if strings.Contains(cur.Error(), secretMarkerValue) {
+			t.Errorf("cause chain leaked secret marker: %v", cur)
+		}
+	}
+
+	if strings.Contains(err.Error(), secretMarkerValue) {
+		t.Errorf("err.Error() leaked secret marker: %q", err.Error())
+	}
+	if strings.Contains(ce.Message, secretMarkerValue) {
+		t.Errorf("Message leaked secret marker: %q", ce.Message)
+	}
+	if strings.Contains(ce.Hint, secretMarkerValue) {
+		t.Errorf("Hint leaked secret marker: %q", ce.Hint)
+	}
+	if strings.Contains(string(sel.Source), secretMarkerValue) {
+		t.Errorf("Selection.Source leaked secret marker: %q", sel.Source)
+	}
+	if strings.Contains(sel.DirectCredentialEnv.AppID, secretMarkerValue) {
+		t.Errorf("Selection.DirectCredentialEnv.AppID leaked secret marker: %q", sel.DirectCredentialEnv.AppID)
+	}
+	for _, k := range sel.DirectCredentialEnv.Keys {
+		if strings.Contains(k, secretMarkerValue) {
+			t.Errorf("Selection.DirectCredentialEnv.Keys leaked secret marker: %q", k)
+		}
+	}
+	// State #7 always clears p.selection on the secret-invalid path (see
+	// doResolveAccount); assert it is zero-valued, which trivially implies no
+	// marker anywhere in it and guards against a future field being populated
+	// from the failed resolution.
+	if sel.Source != "" || sel.DirectCredentialEnv.Present ||
+		sel.DirectCredentialEnv.AppID != "" || len(sel.DirectCredentialEnv.Keys) != 0 {
+		t.Errorf("Selection() = %+v, want zero value on profile_secret_invalid", sel)
+	}
+}
+
+// State #8: P valid, E complete, app_id matches -> profile source, env present+matched.
+func TestSelection_State8_ProfileMatchesEnv(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "cli_a") // matches profile app_id
+	t.Setenv(envvars.CliAppSecret, envSecretValue)
+	writeConfigTenantA(t)
+	cp := newProvider(t, "tenant_a", true)
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if sel.Source != credential.SourceFlagProfile {
+		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceFlagProfile)
+	}
+	if !sel.DirectCredentialEnv.Present || !sel.DirectCredentialEnv.Matched {
+		t.Fatalf("DirectCredentialEnv = %+v, want Present && Matched", sel.DirectCredentialEnv)
+	}
+	if sel.DirectCredentialEnv.AppID != "cli_a" {
+		t.Errorf("DirectCredentialEnv.AppID = %q, want cli_a", sel.DirectCredentialEnv.AppID)
+	}
+	assertNoSecretLeak(t, "state8", string(sel.Source), sel.DirectCredentialEnv.AppID)
+	assertNoSecretLeak(t, "state8-keys", sel.DirectCredentialEnv.Keys...)
+}
+
+// State #9: P valid, E complete, app_id mismatches -> profile_app_credential_conflict.
+func TestSelection_State9_Conflict(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "cli_x") // mismatches profile app_id cli_a
+	t.Setenv(envvars.CliAppSecret, envSecretValue)
+	writeConfigTenantA(t)
+	cp := newProvider(t, "tenant_a", true)
+
+	_, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeProfileAppCredentialConflict {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeProfileAppCredentialConflict)
+	}
+	ve := asValidationError(t, err)
+	if ve.ProfileAppID != "cli_a" {
+		t.Errorf("profile_app_id = %q, want cli_a", ve.ProfileAppID)
+	}
+	if ve.EnvAppID != "cli_x" {
+		t.Errorf("env_app_id = %q, want cli_x", ve.EnvAppID)
+	}
+	assertNoSecretLeak(t, "state9", ve.Message, ve.Hint)
+}
+
+// State #10: P valid, E partial -> app_credential_incomplete (env-partial wins).
+func TestSelection_State10_ProfileWithEnvPartial(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, envSecretValue) // only secret set
+	writeConfigTenantA(t)
+	cp := newProvider(t, "tenant_a", true)
+
+	_, err := cp.Selection(context.Background())
+	if got := subtypeOf(t, err); got != errs.SubtypeAppCredentialIncomplete {
+		t.Fatalf("subtype = %q, want %q", got, errs.SubtypeAppCredentialIncomplete)
+	}
+	ce := asConfigError(t, err)
+	if !slices.Contains(ce.MissingKeys, envvars.CliAppID) {
+		t.Errorf("missing_keys = %v, want to contain %q", ce.MissingKeys, envvars.CliAppID)
+	}
+	assertNoSecretLeak(t, "state10", ce.Message, ce.Hint)
+	assertNoSecretLeak(t, "state10-keys", ce.MissingKeys...)
+}
+
+// fakeSidecarProvider is a NON-env extension provider (Priority 0, Name !=
+// directCredentialProviderName) that always returns a non-nil account. It
+// stands in for the sidecar extension provider without needing a build tag.
+type fakeSidecarProvider struct {
+	appID string
+}
+
+func (f *fakeSidecarProvider) Name() string  { return "sidecar" }
+func (f *fakeSidecarProvider) Priority() int { return 0 }
+func (f *fakeSidecarProvider) ResolveAccount(ctx context.Context) (*extcred.Account, error) {
+	return &extcred.Account{AppID: f.appID, Brand: extcred.Brand("feishu")}, nil
+}
+func (f *fakeSidecarProvider) ResolveToken(ctx context.Context, req extcred.TokenSpec) (*extcred.Token, error) {
+	return &extcred.Token{Value: "sidecar-tok", Source: "sidecar"}, nil
+}
+
+// Regression: a NON-env extension provider (sidecar) that returns an account
+// must win outright even when a profile is set. It must NOT be treated as a
+// direct-credential env account: no profile arbitration, no
+// profile_app_credential_conflict (even though its app_id differs from the
+// profile's cli_a), and DirectCredentialEnv.Present must stay false (§4.2 —
+// no direct env vars are set). This proves the success-account provider gating
+// mirrors the block-path guard.
+func TestSelection_NonEnvExtensionProviderWinsOverProfile(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")     // no direct env credential
+	t.Setenv(envvars.CliAppSecret, "") // no direct env credential
+	writeConfigTenantA(t)              // profile tenant_a exists, app_id cli_a
+
+	sidecar := &fakeSidecarProvider{appID: "sidecar_app"} // differs from cli_a
+	defaultAcct := credential.NewDefaultAccountProvider(func() keychain.KeychainAccess { return &noopKC{} }, "tenant_a")
+	cp := credential.NewCredentialProvider([]extcred.Provider{sidecar}, defaultAcct, nil, nil)
+	cp.WithProfile("tenant_a", true)
+
+	acct, err := cp.ResolveAccount(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	// The sidecar account is used as-is, NOT overridden by profile arbitration.
+	if acct == nil || acct.AppID != "sidecar_app" {
+		t.Fatalf("account = %+v, want AppID sidecar_app (sidecar wins outright)", acct)
+	}
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected Selection error: %v", err)
+	}
+	// No misreported direct env credential (§4.2).
+	if sel.DirectCredentialEnv.Present {
+		t.Errorf("DirectCredentialEnv.Present = true, want false (no direct env vars set)")
+	}
+	// The mismatched app_id (sidecar_app vs profile cli_a) must NOT trigger a
+	// profile_app_credential_conflict: both ResolveAccount and Selection above
+	// returned nil errors, so no conflict (or any other) error was produced.
+	// Guard against a future regression that surfaces a conflict via Selection.
+	if _, selErr := cp.Selection(context.Background()); selErr != nil {
+		if subtypeOf(t, selErr) == errs.SubtypeProfileAppCredentialConflict {
+			t.Errorf("got profile_app_credential_conflict, want none for non-env provider")
+		}
+	}
+	assertNoSecretLeak(t, "nonenv-sidecar", string(sel.Source), sel.DirectCredentialEnv.AppID)
+}
+
+// State #1: P none, E none, C present -> config default (currentApp).
+func TestSelection_State1_ConfigDefault(t *testing.T) {
+	t.Setenv(envvars.CliAppID, "")
+	t.Setenv(envvars.CliAppSecret, "")
+	writeConfigTenantA(t) // CurrentApp = tenant_a
+	cp := newProvider(t, "", false)
+
+	sel, err := cp.Selection(context.Background())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if sel.Source != credential.SourceConfigCurrentApp {
+		t.Fatalf("source = %q, want %q", sel.Source, credential.SourceConfigCurrentApp)
+	}
+}

internal/credential/identity_selection.go

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package credential
+
+// CredentialSourceKind is the wire-stable App/credential selection source.
+type CredentialSourceKind string
+
+const (
+	SourceFlagProfile      CredentialSourceKind = "flag:--profile"
+	SourceEnvProfile       CredentialSourceKind = "env:LARKSUITE_CLI_PROFILE"
+	SourceEnvAppID         CredentialSourceKind = "env:LARKSUITE_CLI_APP_ID"
+	SourceConfigCurrentApp CredentialSourceKind = "config:currentApp"
+	SourceConfigFirstApp   CredentialSourceKind = "config:firstApp"
+)
+
+// DirectCredentialEnv describes the state of direct app credential env vars.
+// It never carries a secret value — only names and the non-sensitive app_id.
+type DirectCredentialEnv struct {
+	Present              bool     `json:"present"`
+	Keys                 []string `json:"keys,omitempty"`
+	AppID                string   `json:"appId,omitempty"`
+	Matched              bool     `json:"matched,omitempty"`
+	ConflictsWithProfile bool     `json:"conflictsWithProfile,omitempty"`
+}
+
+// IdentitySelection is the explainable result of credential selection.
+// It carries NO secret value (security: §5.1).
+type IdentitySelection struct {
+	Source              CredentialSourceKind
+	DirectCredentialEnv DirectCredentialEnv
+}
+
+// Explicit reports whether the identity was actively specified by the
+// user/agent (flag or env), which governs no-fallback behavior.
+func (s IdentitySelection) Explicit() bool {
+	switch s.Source {
+	case SourceFlagProfile, SourceEnvProfile, SourceEnvAppID:
+		return true
+	default:
+		return false
+	}
+}

internal/credential/identity_selection_test.go

@@ -0,0 +1,25 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package credential
+
+import "testing"
+
+func TestIdentitySelectionExplicit(t *testing.T) {
+	cases := []struct {
+		src      CredentialSourceKind
+		explicit bool
+	}{
+		{SourceFlagProfile, true},
+		{SourceEnvProfile, true},
+		{SourceEnvAppID, true},
+		{SourceConfigCurrentApp, false},
+		{SourceConfigFirstApp, false},
+	}
+	for _, c := range cases {
+		sel := IdentitySelection{Source: c.src}
+		if sel.Explicit() != c.explicit {
+			t.Errorf("source %q: Explicit()=%v want %v", c.src, sel.Explicit(), c.explicit)
+		}
+	}
+}

internal/envvars/envvars.go

@@ -10,6 +10,7 @@ const (
 	CliUserAccessToken   = "LARKSUITE_CLI_USER_ACCESS_TOKEN"
 	CliTenantAccessToken = "LARKSUITE_CLI_TENANT_ACCESS_TOKEN"
 	CliDefaultAs         = "LARKSUITE_CLI_DEFAULT_AS"
+	CliProfile           = "LARKSUITE_CLI_PROFILE"
 	CliStrictMode        = "LARKSUITE_CLI_STRICT_MODE"
 
 	// Sidecar proxy (auth proxy mode)

skills/lark-doc/references/style/lark-doc-create-workflow.md

@@ -23,7 +23,7 @@
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
 3. `docs +create` 创建并撰写：
-   - **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
+   - **短文档**：一次写入完整内容
    - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
    - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
    - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
@@ -41,7 +41,6 @@
 7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
 8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入
 
-### 步骤四：专项校验
+### 步骤四：专项校验（按需执行）
 
-9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
-10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现
+9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果

skills/lark-shared/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-shared
 version: 1.0.0
-description: "Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON."
+description: "Use for lark-cli setup/auth/profile-selection tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, handling _notice JSON, profile/tenant/app-identity selection, or any request to make this task/session (or all following lark-cli commands) run under a specific profile/tenant — via LARKSUITE_CLI_PROFILE, --profile, unset LARKSUITE_CLI_PROFILE, or whoami identity diagnostics."
 ---
 
 # lark-cli 共享规则
@@ -32,7 +32,7 @@ lark-cli config init --new
 | 获取全部权限 | `lark-cli auth login --domain all --no-wait --json` |
 | 按业务域授权 | `lark-cli auth login --domain docs --domain drive --no-wait --json`；`--domain` 可重复，也可用逗号分隔 |
 | 指定单个 scope 授权 | `lark-cli auth login --scope "<scope>" --no-wait --json` |
-| 检查当前登录态、是谁登录、token 是否有效 | `lark-cli auth status --json --verify`；回答时引用 `identity`、`verified`、`identities.user.status`、`identities.user.userName`、`identities.user.openId`（用户 open id）、`identities.user.tokenStatus`、`identities.user.scope` |
+| 检查当前登录态、是谁登录、token 是否有效 | 必须运行 `lark-cli auth status --json --verify`；回答时引用 `identity`、`verified`、`identities.user.status`、`identities.user.userName`、`identities.user.openId`（用户 open id）、`identities.user.tokenStatus`、`identities.user.scope` |
 | 快速查看当前身份状态 | `lark-cli whoami`；实际生效的那一个身份 |
 | 退出当前机器的用户登录态 | `lark-cli auth logout --json`；`loggedOut:true` 表示注销成功 |
 | bot 缺少权限 | 不要执行 `auth login`；引导用户在开发者后台开通 bot scope，优先复用错误里的 `console_url` |
@@ -126,6 +126,10 @@ lark-cli auth login --device-code <device_code>
 - **不要在同一轮中展示 URL 后立刻执行 `--device-code`**，这会导致用户看不到 URL
 - **禁止缓存 `verification_url` 或 `device_code`**：每次需要授权时，必须重新执行 `lark-cli auth login --no-wait --json` 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用
 
+## Profile 选择
+
+Profile selection: current state -> `whoami --json`; OAuth/token -> `auth status --json --verify`; agent task -> add `--profile <profile-or-appId>` to every `lark-cli` command; same-shell script/batch -> `LARKSUITE_CLI_PROFILE=<profile-or-appId>` or export/unset; saved config -> `config show` / `profile list`; long-term default -> `profile use`. Ask if the profile is ambiguous; do not set `LARKSUITE_CLI_APP_ID`/`LARKSUITE_CLI_APP_SECRET` unless direct credentials are provided.
+
 ## 更新检查
 
 lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。
@@ -146,24 +150,6 @@ lark-cli update
 
 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
-## JSON 输出契约
-
-`--format json`（默认）下，成功与错误的信封结构不同：
-
-成功信封写入 **stdout**（退出码 0）：
-
-```json
-{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
-```
-
-错误信封写入 **stderr**（退出码非 0）：
-
-```json
-{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
-```
-
-**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
-
 ## 安全规则
 
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。

skills/lark-slides/references/lark-slides-whiteboard.md

@@ -2,8 +2,6 @@
 
 `<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
 
-普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
-
 > 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
 
 ---
@@ -14,13 +12,13 @@
 
 | 场景 | 推荐元素 |
 |------|---------|
-| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
-| 散点图、漏斗图（`<chart>` 不支持）或其他非原生数据视觉 | `<whiteboard>` SVG |
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
 | 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
 | 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
 | 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
 
-> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
 
 ---
 
@@ -41,13 +39,9 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ## SVG 还是 Mermaid？
 
-选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
+选择分两步：**先看图表类型，再看当前模型身份**。
 
-### 第一步：先确认是否应该使用 `<chart>`
-
-如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
-
-### 第二步：whiteboard 类型优先判断
+### 第一步：图表类型优先判断
 
 以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
 
@@ -56,19 +50,20 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 | 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
 | 时序图 | `sequenceDiagram` |
 | 类图 | `classDiagram` |
+| 饼图 | `pie` |
 | 甘特图 | `gantt` |
 | 状态图 | `stateDiagram-v2` |
 | 思维导图 | `mindmap` |
 | ER 图 | `erDiagram` |
 
-### 第三步：非原生图表与装饰元素按模型身份选路径
+### 第二步：数据图表与装饰元素按模型身份选路径
 
 上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
 
 | 模型身份 | 路径 |
 |----------|------|
 | Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
 
 > **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
 
@@ -78,13 +73,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ### ⚠️ 设计品质要求
 
-在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
+在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
 
 - **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
+- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
 - **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
 - **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
-- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
 - **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
 - **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
 
@@ -111,11 +106,11 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 
 | 元素 | 说明 | 典型用途 |
 |------|------|---------|
-| `<rect>` | 矩形，支持 `rx` 圆角 | 卡片、进度条、分段色块 |
+| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
 | `<circle>` | 圆 | 节点、装饰点、环形图 |
 | `<ellipse>` | 椭圆 | 自定义轮廓图形 |
-| `<line>` | 直线 | 轴线、分隔线、连接线 |
-| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、曲线、弧形 |
+| `<line>` | 直线 | 坐标轴、分隔线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
 | `<text>` | 文本，支持中文 | 标签、数值 |
 | `<polygon>` | 多边形 | 箭头、星形、面积填充 |
 | `<g>` | 分组 | 批量变换、语义分组 |
@@ -128,25 +123,27 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 ---
 ### 元素计算
 
-SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
 
 > **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
 
-**散点图 / 装饰性点阵范式**
+**数据图表（柱状图范式）**
 
 ```python
 W, H = 360, 260
 origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
 cw, ch = 290, 184
 
-points = [(12, 40), (28, 80), (45, 65)]
-x_min, x_max, y_min, y_max = 0, 50, 0, 100
-for i, (xv, yv) in enumerate(points):
-    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
-    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
-    print(f"point-{i}: cx={x} cy={y}")
+data, y_max = [120, 160, 90], 200
+bar_w = int(cw / len(data) * 0.62)
+for i, v in enumerate(data):
+    cx = round(origin_x + (i + 0.5) * cw / len(data))
+    y  = round(origin_y - v / y_max * ch)
+    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
 ```
 
+折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
+
 **装饰性元素（等间距范式）**
 
 ```python
@@ -163,9 +160,9 @@ for i in range(n):
 ```python
 # 每个元素登记 (x, y, w, h)，含 stroke 外扩
 elements = [
-    (10, 20, 80, 160),   # item-0
-    (107, 10, 80, 170),  # item-1
-    (204, 40, 80, 140),  # item-2
+    (10, 20, 80, 160),   # bar-0
+    (107, 10, 80, 170),  # bar-1
+    (204, 40, 80, 140),  # bar-2
     (0, 0, 300, 1),      # x-axis
 ]
 
@@ -264,6 +261,7 @@ print(f"whiteboard width={wb_w} height={wb_h}")
 | 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
 | 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
 | 甘特图 | `gantt` | 项目计划、里程碑 |
+| 饼图 | `pie` | 占比数据 |
 | 类图 | `classDiagram` | 对象关系、架构设计 |
 | ER 图 | `erDiagram` | 数据库结构 |
 | 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
@@ -281,6 +279,7 @@ Mermaid 图表会自动撑满 whiteboard 区域。建议：
 |---------|-----------|------------|
 | 流程图（5-8 节点） | 720-816 | 300-400 |
 | 时序图（3-5 参与者） | 720-816 | 320-420 |
+| 饼图 | 500-600 | 300-360 |
 | 甘特图 | 816 | 280-360 |
 | 思维导图 | 816 | 380-480 |
 
@@ -308,7 +307,7 @@ Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解
 - [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
 
 **SVG 模式——视觉品质检查：**
-- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明，没有"裸点"或无解释色块
+- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
 - [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
 - [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
 - [ ] 轴标签与图表元素互不遮挡，留有足够空间

skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -3018,7 +3018,7 @@
 
           子元素(mermaid 与 svg 二选一):
           - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹
-            适用场景: 流程图、时序图、思维导图、类图、甘特图、ER 图、用户旅程等结构图
+            适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表
             特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
             示例: <mermaid><![CDATA[flowchart TD\n  A[开始] --> B[结束]]]></mermaid>
           - svg: SVG 内容

skills/lark-slides/references/xml-format-guide.md

@@ -263,56 +263,7 @@
 - `<chartLegend>`
 - `<chartTooltip>`
 
-完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml)，其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例，以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。
-
-组合图示例（来自 [slides_chart_demo.xml](slides_chart_demo.xml)）：
-
-```xml
-<chart width="556" height="350" topLeftX="42" topLeftY="132">
-  <chartPlotArea>
-    <chartPlot type="combo">
-      <chartExtra/>
-      <chartSeriesList>
-        <chartSeries index="1" comboType="column"/>
-        <chartSeries index="2" comboType="line" yAxisPosition="right">
-          <chartTooltip format="0%"/>
-        </chartSeries>
-      </chartSeriesList>
-    </chartPlot>
-    <chartAxes>
-      <chartAxis type="x">
-        <chartLabel fontSize="10"/>
-      </chartAxis>
-      <chartAxis type="y" position="left">
-        <chartGridLine color="rgb(226, 232, 240)"/>
-        <chartLabel fontSize="10"/>
-      </chartAxis>
-      <chartAxis type="y" position="right">
-        <chartLabel fontSize="10" format="0%"/>
-      </chartAxis>
-    </chartAxes>
-  </chartPlotArea>
-  <chartLegend position="bottom" fontSize="11"/>
-  <chartData>
-    <dim1>
-      <chartField name="季度">24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4</chartField>
-    </dim1>
-    <dim2>
-      <chartField name="营收">180,195,210,245,220,238,258,296</chartField>
-      <chartField name="增速">0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21</chartField>
-    </dim2>
-  </chartData>
-  <chartTitle fontSize="12" color="rgba(15, 30, 58, 1)" bold="true">营收（亿美元, 左轴） · 同比增速（%, 右轴）</chartTitle>
-  <chartStyle>
-    <chartBackground color="rgba(0, 0, 0, 0)"/>
-    <chartBorder color="rgb(222, 224, 227)" width="0"/>
-    <chartColorTheme>
-      <color value="rgb(28, 71, 120)"/>
-      <color value="rgb(240, 129, 54)"/>
-    </chartColorTheme>
-  </chartStyle>
-</chart>
-```
+如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
 
 ## 样式元素
 

skills/lark-slides/references/xml-schema-quick-ref.md

@@ -147,7 +147,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ### whiteboard
 
 ```xml
-<!-- SVG 模式：<chart> 不支持的图表或自定义视觉、装饰元素 -->
+<!-- SVG 模式：数据图表、装饰元素 -->
 <whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
   <svg xmlns="http://www.w3.org/2000/svg">
     <rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>

skills/lark-task/references/lark-task-create.md

@@ -46,20 +46,7 @@ lark-cli task +create --summary "Test Task" --dry-run
 1. Confirm with the user: task summary, due date, assignee, and tasklist if necessary.
    - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status` (it already outputs JSON by default, so do not add `--json`) or `lark-cli contact +get-user` first, extracting `.identities.user.openId` (from `auth status`) or `.data.user.open_id` (from `contact +get-user`), and then passing it to the `--assignee` parameter.
 2. Execute `lark-cli task +create --summary "..." ...`
-3. Judge success by `ok == true` in the stdout JSON (the success envelope has no `code` field — do not test `code == 0`), then report the result: task ID (`data.guid`) and summary.
-
-Example success response:
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": {
-    "guid": "e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx",
-    "url": "https://applink.larkoffice.com/client/todo/detail?guid=e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx"
-  }
-}
-```
+3. Report the result: task ID and summary.
 
 > [!CAUTION]
 > This is a **Write Operation** -- You must confirm the user's intent before executing.