fix(credential): propagate malformed-config error for explicit profile

When an explicit profile was requested and LoadMultiAppConfig failed, the error was discarded and every failure reported as profile_not_found, masking a real config problem (e.g. malformed file) behind a misleading "run profile list" hint. Propagate the underlying error when it is a malformed-config failure (errors.Is ErrMalformedConfig) so errors.Is / errors.Unwrap keep working, mirroring the no-profile branch. An absent config is not malformed and still yields the friendly profile_not_found.
docs(lark-shared): refine profile-selection guidance
2026-07-07 17:45:15 +08:00 · 2026-07-07 15:33:44 +08:00 · 2026-07-07 14:47:16 +08:00 · 2026-07-07 14:47:16 +08:00 · 2026-07-07 11:28:13 +08:00 · 2026-07-07 11:27:34 +08:00
35 changed files with 1453 additions and 788 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,27 +2,6 @@

 All notable changes to this project will be documented in this file.

-## [v1.0.66] - 2026-07-06
-
-### Features
-
- support semantic recurring calendar operations (#1723)
-
-### Bug Fixes
-
- guide drive import concurrency conflicts (#1751)
- **calendar**: guide approval room booking fallback (#1637)
- support pnpm global installs in self-update (#1705)
-
-### Documentation
-
- tighten doc creation validation workflow (#1759)
- clarify success envelope contract — judge success by ok, not code (#1730)
-
-### Refactoring
-
- **envvars**: consolidate agent env value access (#1757)
-
 ## [v1.0.65] - 2026-07-03

 ### Features
@@ -1392,7 +1371,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.

-[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
 [v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
--- a/README.md
+++ b/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
--- a/README.zh.md
+++ b/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
--- a/cmd/auth/status.go
+++ b/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)
--- a/cmd/auth/status_test.go
+++ b/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,
--- a/cmd/bootstrap.go
+++ b/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
 }
--- a/cmd/bootstrap_test.go
+++ b/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")
+		}
+	})
+}
--- a/cmd/profile/profile.go
+++ b/cmd/profile/profile.go
@@ -14,6 +14,13 @@ 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:
+  --profile <name>             Use a profile for this command only.
+  LARKSUITE_CLI_PROFILE        Use a profile for the current shell / agent session.
+  lark-cli whoami --json       Show which identity is actually used.
+  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{
--- a/cmd/profile/profile_test.go
+++ b/cmd/profile/profile_test.go
@@ -627,6 +627,19 @@ 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")
+	}
+}
+
 func TestProfileListRun_InvalidConfigReturnsValidationError(t *testing.T) {
 	dir := setupProfileConfigDir(t)
 	if err := os.WriteFile(filepath.Join(dir, "config.json"), []byte("{invalid json"), 0600); err != nil {
--- a/cmd/update/update.go
+++ b/cmd/update/update.go
@@ -102,8 +102,7 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 		Long: `Update lark-cli to the latest version.

 Detects the installation method automatically:
-  - npm install:  runs npm install -g @larksuite/cli@<version>
-  - pnpm install: runs pnpm add -g @larksuite/cli@<version>
+  - npm install: runs npm install -g @larksuite/cli@<version>
  - manual/other: shows GitHub Releases download URL

 Use --json for structured output (for AI agents and scripts).
@@ -165,7 +164,7 @@ func updateRun(opts *UpdateOptions) error {
 	if !detect.CanAutoUpdate() {
 		return doManualUpdate(opts, io, cur, latest, detect, updater)
 	}
-	return doAutoUpdate(opts, io, cur, latest, detect, updater)
+	return doNpmUpdate(opts, io, cur, latest, updater)
 }

 // --- Output helpers ---
@@ -227,23 +226,12 @@ func doManualUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest stri
 	fmt.Fprintf(io.ErrOut, "To update manually, download the latest release:\n")
 	fmt.Fprintf(io.ErrOut, "  Release:   %s\n", releaseURL(latest))
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
-	if detect.Method == selfupdate.InstallPnpm {
-		fmt.Fprintf(io.ErrOut, "\nOr install via pnpm (note: skills will not be synced):\n  pnpm add -g %s@%s\n  pnpm dlx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
-	} else {
-		fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
-	}
+	fmt.Fprintf(io.ErrOut, "\nOr install via npm (note: skills will not be synced):\n  npm install -g %s@%s\n  npx skills add larksuite/cli -y -g   # sync skills separately\n", selfupdate.NpmPackage, latest)
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }

-func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, detect selfupdate.DetectResult, updater *selfupdate.Updater) error {
-	pm := "npm"
-	install := updater.RunNpmInstall
-	if detect.Method == selfupdate.InstallPnpm {
-		pm = "pnpm"
-		install = updater.RunPnpmInstall
-	}
-
+func doNpmUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string, updater *selfupdate.Updater) error {
 	restore, err := updater.PrepareSelfReplace()
 	if err != nil {
 		return reportError(opts, io, "update_error",
@@ -251,19 +239,19 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	}

 	if !opts.JSON {
-		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via %s ...\n", cur, symArrow(), latest, pm)
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli %s %s %s via npm ...\n", cur, symArrow(), latest)
 	}

-	npmResult := install(latest)
+	npmResult := updater.RunNpmInstall(latest)
 	if npmResult.Err != nil {
 		restore()
 		combined := npmResult.CombinedOutput()
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok": false, "error": map[string]interface{}{
-					"type": "update_error", "message": fmt.Sprintf("%s install failed: %s", pm, npmResult.Err),
+					"type": "update_error", "message": fmt.Sprintf("npm install failed: %s", npmResult.Err),
 					"detail": selfupdate.Truncate(combined, maxNpmOutput),
-					"hint":   permissionHint(combined, pm),
+					"hint":   permissionHint(combined),
 				},
 			})
 			return output.ErrBare(output.ExitAPI)
@@ -275,7 +263,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 			fmt.Fprint(io.ErrOut, npmResult.Stderr.String())
 		}
 		fmt.Fprintf(io.ErrOut, "\n%s Update failed: %s\n", symFail(), npmResult.Err)
-		if hint := permissionHint(combined, pm); hint != "" {
+		if hint := permissionHint(combined); hint != "" {
 			fmt.Fprintf(io.ErrOut, "  %s\n", hint)
 		}
 		return output.ErrBare(output.ExitAPI)
@@ -286,7 +274,7 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	if err := updater.VerifyBinary(latest); err != nil {
 		restore()
 		msg := fmt.Sprintf("new binary verification failed: %s", err)
-		hint := verificationFailureHint(updater, latest, pm)
+		hint := verificationFailureHint(updater, latest)
 		if opts.JSON {
 			output.PrintJson(io.Out, map[string]interface{}{
 				"ok":    false,
@@ -316,33 +304,23 @@ func doAutoUpdate(opts *UpdateOptions, io *cmdutil.IOStreams, cur, latest string
 	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli from %s to %s\n", symOK(), cur, latest)
 	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
 	if skillsResult != nil {
-		skillsPM := "npx"
-		if detect.Method == selfupdate.InstallPnpm && detect.PnpmAvailable {
-			skillsPM = "pnpm dlx"
-		}
-		fmt.Fprintf(io.ErrOut, "\nUpdating skills via %s ...\n", skillsPM)
+		fmt.Fprintf(io.ErrOut, "\nUpdating skills ...\n")
 	}
 	emitSkillsTextHints(io, skillsResult)
 	return nil
 }

-func permissionHint(pmOutput, pm string) string {
-	if !strings.Contains(pmOutput, "EACCES") || isWindows() {
-		return ""
+func permissionHint(npmOutput string) string {
+	if strings.Contains(npmOutput, "EACCES") && !isWindows() {
+		return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
 	}
-	if pm == "pnpm" {
-		return "Permission denied. Ensure your pnpm global directory is writable — re-run `pnpm setup`, or see https://pnpm.io/pnpm-cli"
-	}
-	return "Permission denied. Try: sudo lark-cli update, or adjust your npm global prefix: https://docs.npmjs.com/resolving-eacces-permissions-errors"
+	return ""
 }

-func verificationFailureHint(updater *selfupdate.Updater, latest, pm string) string {
+func verificationFailureHint(updater *selfupdate.Updater, latest string) string {
 	if updater.CanRestorePreviousVersion() {
 		return "the previous version has been restored"
 	}
-	if pm == "pnpm" {
-		return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): pnpm add -g %s@%s && pnpm dlx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
-	}
 	return fmt.Sprintf("automatic rollback is unavailable on this platform; reinstall manually (skills will not be synced): npm install -g %s@%s && npx skills add larksuite/cli -y -g, or download %s", selfupdate.NpmPackage, latest, releaseURL(latest))
 }

--- a/cmd/update/update_test.go
+++ b/cmd/update/update_test.go
@@ -57,27 +57,6 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 	t.Cleanup(func() { newUpdater = origNew })
 }

-// mockDetectAndPnpm mirrors mockDetectAndNpm but wires the pnpm install path
-// and fails the test if the npm install path is invoked.
-func mockDetectAndPnpm(t *testing.T, result selfupdate.DetectResult, pnpmFn func(string) *selfupdate.NpmResult) {
-	t.Helper()
-	origNew := newUpdater
-	newUpdater = func() *selfupdate.Updater {
-		u := selfupdate.New()
-		u.DetectOverride = func() selfupdate.DetectResult { return result }
-		u.PnpmInstallOverride = pnpmFn
-		u.NpmInstallOverride = func(string) *selfupdate.NpmResult {
-			t.Errorf("npm install must not be called for a pnpm install")
-			return &selfupdate.NpmResult{}
-		}
-		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
-		u.SkillsCommandOverride = successfulSkillsCommand()
-		return u
-	}
-	t.Cleanup(func() { newUpdater = origNew })
-}
-
 func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
 	return func() *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
@@ -102,110 +81,6 @@ func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	}
 }

-func TestUpdatePnpm_JSON(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _ := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json"})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-	)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	if out := stdout.String(); !strings.Contains(out, `"action": "updated"`) {
-		t.Errorf("expected updated in output, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_Human(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, stderr := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} },
-	)
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stderr.String()
-	if !strings.Contains(out, "via pnpm") {
-		t.Errorf("expected 'via pnpm' in stderr, got: %s", out)
-	}
-	if !strings.Contains(out, "Updating skills via pnpm dlx ...") {
-		t.Errorf("expected skills sync to report pnpm dlx launcher, got: %s", out)
-	}
-	if !strings.Contains(out, "Successfully updated") {
-		t.Errorf("expected success message, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_InstallError_JSON(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _ := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{"--json"})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetectAndPnpm(t,
-		selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: true},
-		func(string) *selfupdate.NpmResult { return &selfupdate.NpmResult{Err: errors.New("pnpm boom")} },
-	)
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatal("expected error exit")
-	}
-	if out := stdout.String(); !strings.Contains(out, `"ok": false`) || !strings.Contains(out, "update_error") {
-		t.Errorf("expected failure envelope, got: %s", out)
-	}
-	if out := stdout.String(); !strings.Contains(out, "pnpm install failed") {
-		t.Errorf("expected message to report pnpm as the package manager, got: %s", out)
-	}
-}
-
-func TestUpdatePnpm_Unavailable_ManualFallback(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, stderr := newTestFactory(t)
-	cmd := NewCmdUpdate(f)
-	cmd.SetArgs([]string{})
-	origFetch := fetchLatest
-	fetchLatest = func() (string, error) { return "2.0.0", nil }
-	defer func() { fetchLatest = origFetch }()
-	origVersion := currentVersion
-	currentVersion = func() string { return "1.0.0" }
-	defer func() { currentVersion = origVersion }()
-	mockDetect(t, selfupdate.DetectResult{Method: selfupdate.InstallPnpm, ResolvedPath: "/x/node_modules/.pnpm/@larksuite+cli@1.0.0/node_modules/@larksuite/cli/bin/lark-cli", PnpmAvailable: false})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	out := stderr.String()
-	if !strings.Contains(out, "installed via pnpm, but pnpm is not available in PATH") {
-		t.Errorf("expected pnpm manual reason, got: %s", out)
-	}
-	if !strings.Contains(out, "pnpm add -g") {
-		t.Errorf("expected pnpm add -g hint, got: %s", out)
-	}
-}
-
 func TestNormalizeVersion(t *testing.T) {
 	tests := []struct {
 		input string
@@ -391,9 +266,6 @@ func TestUpdateNpm_Human(t *testing.T) {
 	if !strings.Contains(out, "Successfully updated") {
 		t.Errorf("expected success message in stderr, got: %s", out)
 	}
-	if !strings.Contains(out, "Updating skills via npx ...") {
-		t.Errorf("expected skills sync to report npx launcher for npm install, got: %s", out)
-	}
 }

 func TestUpdateForce_JSON(t *testing.T) {
@@ -867,9 +739,9 @@ func TestPermissionHint(t *testing.T) {
 	origOS := currentOS
 	defer func() { currentOS = origOS }()

-	// Linux + npm: EACCES should produce a hint with npm prefix guidance.
+	// Linux: EACCES should produce a hint with npm prefix guidance.
 	currentOS = "linux"
-	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'", "npm")
+	hint := permissionHint("EACCES: permission denied, access '/usr/local/lib'")
 	if !strings.Contains(hint, "npm global prefix") {
 		t.Errorf("expected npm prefix hint on linux, got: %s", hint)
 	}
@@ -877,25 +749,16 @@ func TestPermissionHint(t *testing.T) {
 		t.Errorf("should not suggest raw sudo npm install, got: %s", hint)
 	}

-	// Linux + pnpm: EACCES should point at pnpm setup, not npm prefix/sudo.
-	pnpmHint := permissionHint("EACCES: permission denied, access '/Users/x/Library/pnpm'", "pnpm")
-	if !strings.Contains(pnpmHint, "pnpm setup") {
-		t.Errorf("expected pnpm setup hint, got: %s", pnpmHint)
-	}
-	if strings.Contains(pnpmHint, "npm global prefix") || strings.Contains(pnpmHint, "sudo") {
-		t.Errorf("pnpm hint must not reference npm prefix or sudo, got: %s", pnpmHint)
-	}
-
 	// Windows: EACCES hint is suppressed (no EACCES on Windows).
 	currentOS = "windows"
-	hint = permissionHint("EACCES: permission denied", "npm")
+	hint = permissionHint("EACCES: permission denied")
 	if hint != "" {
 		t.Errorf("expected empty hint on Windows, got: %s", hint)
 	}

 	// Non-EACCES error: always empty.
 	currentOS = "linux"
-	if got := permissionHint("some other error", "npm"); got != "" {
+	if got := permissionHint("some other error"); got != "" {
 		t.Errorf("expected empty hint for non-EACCES, got: %s", got)
 	}
 }
--- a/cmd/whoami/whoami.go
+++ b/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.
--- a/cmd/whoami/whoami_test.go
+++ b/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)
+	}
+}
--- a/errs/ERROR_CONTRACT.md
+++ b/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 |
--- a/errs/marshal_test.go
+++ b/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"},
--- a/errs/subtypes.go
+++ b/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
--- a/errs/types.go
+++ b/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
--- a/errs/types_test.go
+++ b/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)
+	}
+}
--- a/internal/cmdutil/factory.go
+++ b/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 {
--- a/internal/cmdutil/factory_default.go
+++ b/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)
 }
--- a/internal/cmdutil/secheader.go
+++ b/internal/cmdutil/secheader.go
@@ -6,10 +6,12 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"os"
 	"reflect"
 	"runtime/debug"
 	"strings"
 	"sync"
+	"unicode"

 	"github.com/larksuite/cli/extension/credential"
 	"github.com/larksuite/cli/extension/fileio"
@@ -38,6 +40,8 @@ const (
 	BuildKindUnknown  = "unknown"

 	officialModulePath = "github.com/larksuite/cli"
+
+	agentTraceMaxLen = 1024
 )

 // UserAgentValue returns the User-Agent value: "lark-cli/{version}".
@@ -45,6 +49,25 @@ func UserAgentValue() string {
 	return SourceValue + "/" + build.Version
 }

+// AgentTraceValue returns a header-safe value from the
+// LARKSUITE_CLI_AGENT_TRACE environment variable. It trims
+// surrounding whitespace, rejects values containing any Unicode
+// control character or exceeding agentTraceMaxLen, and returns ""
+// for any invalid or empty value. Callers can use the result
+// directly in HTTP headers without further sanitisation.
+func AgentTraceValue() string {
+	v := strings.TrimSpace(os.Getenv(envvars.CliAgentTrace))
+	if v == "" || len(v) > agentTraceMaxLen {
+		return ""
+	}
+	for _, r := range v {
+		if unicode.IsControl(r) {
+			return ""
+		}
+	}
+	return v
+}
+
 // BaseSecurityHeaders returns headers that every request must carry.
 func BaseSecurityHeaders() http.Header {
 	h := make(http.Header)
@@ -52,7 +75,7 @@ func BaseSecurityHeaders() http.Header {
 	h.Set(HeaderVersion, build.Version)
 	h.Set(HeaderBuild, DetectBuildKind())
 	h.Set(HeaderUserAgent, UserAgentValue())
-	if v := envvars.AgentTrace(); v != "" {
+	if v := AgentTraceValue(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
 	return h
--- a/internal/cmdutil/secheader_test.go
+++ b/internal/cmdutil/secheader_test.go
@@ -6,6 +6,7 @@ package cmdutil
 import (
 	"context"
 	"net/http"
+	"strings"
 	"testing"

 	"github.com/larksuite/cli/extension/credential"
@@ -263,9 +264,88 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }

 // ---------------------------------------------------------------------------
-// HeaderAgentTrace injection (via BaseSecurityHeaders)
+// AgentTraceValue / HeaderAgentTrace
 // ---------------------------------------------------------------------------

+func TestAgentTraceValue_EmptyWhenEnvUnset(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty when env unset", got)
+	}
+}
+
+func TestAgentTraceValue_ReturnsCleanValue(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "trace-abc-123")
+	if got := AgentTraceValue(); got != "trace-abc-123" {
+		t.Fatalf("AgentTraceValue() = %q, want %q", got, "trace-abc-123")
+	}
+}
+
+func TestAgentTraceValue_TrimsWhitespace(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "  trace-trim  ")
+	if got := AgentTraceValue(); got != "trace-trim" {
+		t.Fatalf("AgentTraceValue() = %q, want %q (whitespace trimmed)", got, "trace-trim")
+	}
+}
+
+func TestAgentTraceValue_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "   ")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for whitespace-only value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsCRLF(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\r\nX-Evil: attack")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for CR/LF value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsLF(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\nX-Evil: attack")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for LF value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsTab(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\tinjected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for tab value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsControlChar(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\x01injected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for control char value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsDEL(t *testing.T) {
+	t.Setenv(envvars.CliAgentTrace, "val\x7finjected")
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() = %q, want empty for DEL value", got)
+	}
+}
+
+func TestAgentTraceValue_RejectsOverlongValue(t *testing.T) {
+	longVal := strings.Repeat("a", agentTraceMaxLen+1)
+	t.Setenv(envvars.CliAgentTrace, longVal)
+	if got := AgentTraceValue(); got != "" {
+		t.Fatalf("AgentTraceValue() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
+	}
+}
+
+func TestAgentTraceValue_AcceptsMaxLengthValue(t *testing.T) {
+	val := strings.Repeat("a", agentTraceMaxLen)
+	t.Setenv(envvars.CliAgentTrace, val)
+	if got := AgentTraceValue(); got != val {
+		t.Fatalf("AgentTraceValue() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
+	}
+}
+
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()
--- a/internal/credential/credential_provider.go
+++ b/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.
--- a/internal/credential/credential_provider_selection_test.go
+++ b/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)
+	}
+}
--- a/internal/credential/identity_selection.go
+++ b/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
+	}
+}
--- a/internal/credential/identity_selection_test.go
+++ b/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)
+		}
+	}
+}
--- a/internal/envvars/envvars.go
+++ b/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)
@@ -19,7 +20,6 @@ const (
 	// Content safety scanning mode
 	CliContentSafetyMode = "LARKSUITE_CLI_CONTENT_SAFETY_MODE"

-	CliAgentName  = "LARKSUITE_CLI_AGENT_NAME"
 	CliAgentTrace = "LARKSUITE_CLI_AGENT_TRACE"

 	CliProxyEnable  = "LARKSUITE_CLI_PROXY_ENABLE"
--- a/internal/envvars/read.go
+++ b/internal/envvars/read.go
@@ -1,36 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package envvars
-
-import (
-	"os"
-	"strings"
-	"unicode"
-)
-
-const (
-	agentNameMaxLen  = 128
-	agentTraceMaxLen = 1024
-)
-
-func AgentName() string {
-	return sanitizeSingleLine(os.Getenv(CliAgentName), agentNameMaxLen)
-}
-
-func AgentTrace() string {
-	return sanitizeSingleLine(os.Getenv(CliAgentTrace), agentTraceMaxLen)
-}
-
-func sanitizeSingleLine(raw string, maxLen int) string {
-	v := strings.TrimSpace(raw)
-	if v == "" || len(v) > maxLen {
-		return ""
-	}
-	for _, r := range v {
-		if unicode.IsControl(r) {
-			return ""
-		}
-	}
-	return v
-}
--- a/internal/envvars/read_test.go
+++ b/internal/envvars/read_test.go
@@ -1,131 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package envvars
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(CliAgentName, "")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentName_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentName, "claude-code")
-	if got := AgentName(); got != "claude-code" {
-		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
-	}
-}
-
-func TestAgentName_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentName, "  cursor  ")
-	if got := AgentName(); got != "cursor" {
-		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
-	}
-}
-
-func TestAgentName_RejectsCRLFInjection(t *testing.T) {
-	t.Setenv(CliAgentName, "agent\r\nX-Evil: attack")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentName_RejectsControlChar(t *testing.T) {
-	t.Setenv(CliAgentName, "agent\x01injected")
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentName_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentNameMaxLen+1)
-	t.Setenv(CliAgentName, longVal)
-	if got := AgentName(); got != "" {
-		t.Fatalf("AgentName() returned non-empty for %d-byte value (max %d)", len(longVal), agentNameMaxLen)
-	}
-}
-
-func TestAgentTrace_EmptyWhenEnvUnset(t *testing.T) {
-	t.Setenv(CliAgentTrace, "")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty when env unset", got)
-	}
-}
-
-func TestAgentTrace_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentTrace, "trace-abc-123")
-	if got := AgentTrace(); got != "trace-abc-123" {
-		t.Fatalf("AgentTrace() = %q, want %q", got, "trace-abc-123")
-	}
-}
-
-func TestAgentTrace_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentTrace, "  trace-trim  ")
-	if got := AgentTrace(); got != "trace-trim" {
-		t.Fatalf("AgentTrace() = %q, want %q (whitespace trimmed)", got, "trace-trim")
-	}
-}
-
-func TestAgentTrace_OnlyWhitespace_ReturnsEmpty(t *testing.T) {
-	t.Setenv(CliAgentTrace, "   ")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for whitespace-only value", got)
-	}
-}
-
-func TestAgentTrace_RejectsCRLF(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\r\nX-Evil: attack")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for CR/LF value", got)
-	}
-}
-
-func TestAgentTrace_RejectsLF(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\nX-Evil: attack")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for LF value", got)
-	}
-}
-
-func TestAgentTrace_RejectsTab(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\tinjected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for tab value", got)
-	}
-}
-
-func TestAgentTrace_RejectsControlChar(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\x01injected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for control char value", got)
-	}
-}
-
-func TestAgentTrace_RejectsDEL(t *testing.T) {
-	t.Setenv(CliAgentTrace, "val\x7finjected")
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() = %q, want empty for DEL value", got)
-	}
-}
-
-func TestAgentTrace_RejectsOverlongValue(t *testing.T) {
-	longVal := strings.Repeat("a", agentTraceMaxLen+1)
-	t.Setenv(CliAgentTrace, longVal)
-	if got := AgentTrace(); got != "" {
-		t.Fatalf("AgentTrace() returned non-empty for %d-byte value (max %d)", len(longVal), agentTraceMaxLen)
-	}
-}
-
-func TestAgentTrace_AcceptsMaxLengthValue(t *testing.T) {
-	val := strings.Repeat("a", agentTraceMaxLen)
-	t.Setenv(CliAgentTrace, val)
-	if got := AgentTrace(); got != val {
-		t.Fatalf("AgentTrace() = %q, want %d-byte value accepted", got, agentTraceMaxLen)
-	}
-}
--- a/internal/selfupdate/updater.go
+++ b/internal/selfupdate/updater.go
@@ -32,7 +32,6 @@ type InstallMethod int

 const (
 	InstallNpm InstallMethod = iota
-	InstallPnpm
 	InstallManual
 )

@@ -54,32 +53,22 @@ var (

 // DetectResult holds installation detection results.
 type DetectResult struct {
-	Method        InstallMethod
-	ResolvedPath  string
-	NpmAvailable  bool
-	PnpmAvailable bool
+	Method       InstallMethod
+	ResolvedPath string
+	NpmAvailable bool
 }

 // CanAutoUpdate returns true if the CLI can update itself automatically.
 func (d DetectResult) CanAutoUpdate() bool {
-	switch d.Method {
-	case InstallNpm:
-		return d.NpmAvailable
-	case InstallPnpm:
-		return d.PnpmAvailable
-	}
-	return false
+	return d.Method == InstallNpm && d.NpmAvailable
 }

 // ManualReason returns a human-readable explanation of why auto-update is unavailable.
 func (d DetectResult) ManualReason() string {
-	switch {
-	case d.Method == InstallNpm && !d.NpmAvailable:
+	if d.Method == InstallNpm && !d.NpmAvailable {
 		return "installed via npm, but npm is not available in PATH"
-	case d.Method == InstallPnpm && !d.PnpmAvailable:
-		return "installed via pnpm, but pnpm is not available in PATH"
 	}
-	return "not installed via npm or pnpm"
+	return "not installed via npm"
 }

 // NpmResult holds the result of an npm install or skills update execution.
@@ -103,7 +92,6 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
-	PnpmInstallOverride      func(version string) *NpmResult
 	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
@@ -113,38 +101,17 @@ type Updater struct {
 	// running binary is successfully renamed to .old. Used by
 	// CanRestorePreviousVersion to report whether rollback is possible.
 	backupCreated bool
-
-	// detectCache memoizes the first real DetectInstallMethod result. How this
-	// binary was installed cannot change during a single process, so caching is
-	// the correct semantics — and it is required for correctness: the update
-	// flow mutates the install (pnpm add -g / npm install -g) before syncing
-	// skills, so a re-detection at skills time could resolve a now-stale
-	// os.Executable path and misclassify. Seeded pre-update by the first call
-	// (updateRun), it keeps the post-update skills launcher consistent with the
-	// launcher reported to the user. Not goroutine-safe; the update flow is
-	// sequential.
-	detectCache *DetectResult
 }

 // New creates an Updater with default (real) behavior.
 func New() *Updater { return &Updater{} }

-// DetectInstallMethod determines how the CLI was installed and whether the
-// owning package manager is available for auto-update.
+// DetectInstallMethod determines how the CLI was installed and whether
+// npm is available for auto-update.
 func (u *Updater) DetectInstallMethod() DetectResult {
 	if u.DetectOverride != nil {
 		return u.DetectOverride()
 	}
-	if u.detectCache != nil {
-		return *u.detectCache
-	}
-	result := u.detectInstallMethod()
-	u.detectCache = &result
-	return result
-}
-
-// detectInstallMethod performs the real (uncached) detection.
-func (u *Updater) detectInstallMethod() DetectResult {
 	exe, err := vfs.Executable()
 	if err != nil {
 		return DetectResult{Method: InstallManual}
@@ -153,54 +120,24 @@ func (u *Updater) detectInstallMethod() DetectResult {
 	if err != nil {
 		return DetectResult{Method: InstallManual, ResolvedPath: exe}
 	}
-	_, npmErr := exec.LookPath("npm")
-	_, pnpmErr := exec.LookPath("pnpm")
-	return detectFromResolved(resolved, npmErr == nil, pnpmErr == nil)
-}

-// detectFromResolved classifies the resolved binary path into an install
-// method and records package-manager availability. Split out from
-// DetectInstallMethod so the classification is unit-testable without touching
-// the filesystem or PATH.
-func detectFromResolved(resolved string, npmOnPath, pnpmOnPath bool) DetectResult {
 	method := InstallManual
 	if strings.Contains(resolved, "node_modules") {
-		if containsPnpmMarker(resolved) {
-			method = InstallPnpm
-		} else {
-			method = InstallNpm
-		}
+		method = InstallNpm
 	}
-	d := DetectResult{Method: method, ResolvedPath: resolved}
-	switch method {
-	case InstallNpm:
-		d.NpmAvailable = npmOnPath
-	case InstallPnpm:
-		d.PnpmAvailable = pnpmOnPath
-	}
-	return d
-}

-// containsPnpmMarker reports whether the resolved binary path belongs to a
-// pnpm-managed install. pnpm exposes two layouts: the classic virtual store
-// (a ".pnpm" directory segment) and the global content-addressable store,
-// whose resolved path runs through pnpm's home directory (e.g.
-// "~/Library/pnpm/store/v11/links/...") — a "pnpm" segment immediately
-// followed by "store". Matching only these two shapes (rather than any bare
-// "pnpm" segment) avoids misclassifying an npm install that merely lives under
-// a directory named "pnpm". Windows separators are normalized to "/" so the
-// classification is OS-independent and unit-testable anywhere.
-func containsPnpmMarker(p string) bool {
-	parts := strings.Split(strings.ReplaceAll(p, `\`, "/"), "/")
-	for i, part := range parts {
-		if part == ".pnpm" {
-			return true
-		}
-		if part == "pnpm" && i+1 < len(parts) && parts[i+1] == "store" {
-			return true
+	npmAvailable := false
+	if method == InstallNpm {
+		if _, err := exec.LookPath("npm"); err == nil {
+			npmAvailable = true
 		}
 	}
-	return false
+
+	return DetectResult{
+		Method:       method,
+		ResolvedPath: resolved,
+		NpmAvailable: npmAvailable,
+	}
 }

 // RunNpmInstall executes npm install -g @larksuite/cli@<version>.
@@ -226,29 +163,6 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }

-// RunPnpmInstall executes pnpm add -g @larksuite/cli@<version>.
-func (u *Updater) RunPnpmInstall(version string) *NpmResult {
-	if u.PnpmInstallOverride != nil {
-		return u.PnpmInstallOverride(version)
-	}
-	r := &NpmResult{}
-	pnpmPath, err := exec.LookPath("pnpm")
-	if err != nil {
-		r.Err = fmt.Errorf("pnpm not found in PATH: %w", err)
-		return r
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), npmInstallTimeout)
-	defer cancel()
-	cmd := exec.CommandContext(ctx, pnpmPath, "add", "-g", NpmPackage+"@"+version)
-	cmd.Stdout = &r.Stdout
-	cmd.Stderr = &r.Stderr
-	r.Err = cmd.Run()
-	if ctx.Err() == context.DeadlineExceeded {
-		r.Err = fmt.Errorf("pnpm install timed out after %s", npmInstallTimeout)
-	}
-	return r
-}
-
 func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
 	if u.SkillsIndexFetchOverride != nil {
 		return u.SkillsIndexFetchOverride()
@@ -347,40 +261,19 @@ func (u *Updater) runSkillsInstall(source string, nameList []string) *NpmResult
 	return u.runSkillsCommand(args...)
 }

-// skillsInvocation decides how to launch the `skills` CLI. When the lark-cli
-// itself was installed via pnpm and pnpm is available, it uses `pnpm dlx` so
-// pnpm-only environments (pnpm's standalone installer bundles Node without
-// putting npm/npx on PATH) can still sync skills after a self-update.
-// Otherwise it uses `npx`. The npx auto-confirm flag "-y", when present as the
-// leading arg, maps to `pnpm dlx`'s default non-interactive behavior and is
-// dropped for the pnpm launcher. Kept pure (no exec/PATH access) so the
-// launcher selection is unit-testable on any platform.
-func skillsInvocation(method InstallMethod, pnpmAvailable bool, args []string) (launcher string, rest []string) {
-	if method == InstallPnpm && pnpmAvailable {
-		r := args
-		if len(r) > 0 && r[0] == "-y" {
-			r = r[1:]
-		}
-		return "pnpm", append([]string{"dlx"}, r...)
-	}
-	return "npx", args
-}
-
 func (u *Updater) runSkillsCommand(args ...string) *NpmResult {
 	if u.SkillsCommandOverride != nil {
 		return u.SkillsCommandOverride(args...)
 	}
 	r := &NpmResult{}
-	det := u.DetectInstallMethod()
-	launcher, cmdArgs := skillsInvocation(det.Method, det.PnpmAvailable, args)
-	binPath, err := exec.LookPath(launcher)
+	npxPath, err := exec.LookPath("npx")
 	if err != nil {
-		r.Err = fmt.Errorf("%s not found in PATH: %w", launcher, err)
+		r.Err = fmt.Errorf("npx not found in PATH: %w", err)
 		return r
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), skillsUpdateTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, binPath, cmdArgs...)
+	cmd := exec.CommandContext(ctx, npxPath, args...)
 	cmd.Stdout = &r.Stdout
 	cmd.Stderr = &r.Stderr
 	r.Err = cmd.Run()
--- a/internal/selfupdate/updater_test.go
+++ b/internal/selfupdate/updater_test.go
@@ -371,147 +371,3 @@ func TestListOfficialSkillsFallsBack(t *testing.T) {
 		t.Fatalf("fallback call = %q, want larksuite/cli --list", called[1])
 	}
 }
-
-func TestContainsPnpmMarker(t *testing.T) {
-	cases := []struct {
-		path string
-		want bool
-	}{
-		// Classic virtual-store layout (.pnpm segment).
-		{"/Users/x/Library/pnpm/global/5/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{`C:\Users\x\AppData\Local\pnpm\global\5\node_modules\.pnpm\@larksuite+cli@1.0.44\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
-		// Global content-addressable store layout (pnpm 11): resolved path runs
-		// through the pnpm home store, a "pnpm" segment with no ".pnpm".
-		{"/Users/x/Library/pnpm/store/v11/links/@larksuite/cli/1.0.59/abc123/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{"/home/x/.local/share/pnpm/store/v10/@larksuite/cli/node_modules/@larksuite/cli/bin/lark-cli", true},
-		{`C:\Users\x\AppData\Local\pnpm\store\v11\links\@larksuite\cli\node_modules\@larksuite\cli\bin\lark-cli.exe`, true},
-		// npm and non-package installs — no pnpm/.pnpm segment.
-		{"/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
-		{"/usr/local/bin/lark-cli", false},
-		// Substrings that must NOT match: segment must be exactly .pnpm, or
-		// "pnpm" immediately followed by "store".
-		{"/opt/homebrew/.pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
-		{"/opt/pnpmfoo/node_modules/@larksuite/cli/bin/lark-cli", false},
-		// A bare "pnpm" directory NOT followed by "store" (e.g. an npm install
-		// living under a dir named pnpm) must not be misclassified as pnpm.
-		{"/opt/pnpm/lib/node_modules/@larksuite/cli/bin/lark-cli", false},
-	}
-	for _, c := range cases {
-		if got := containsPnpmMarker(c.path); got != c.want {
-			t.Errorf("containsPnpmMarker(%q) = %v, want %v", c.path, got, c.want)
-		}
-	}
-}
-
-func TestDetectInstallMethod_Pnpm(t *testing.T) {
-	u := &Updater{DetectOverride: nil}
-	u.DetectOverride = func() DetectResult {
-		// Exercise the real classification by feeding a resolved path via a small shim.
-		return detectFromResolved("/x/node_modules/.pnpm/@larksuite+cli@1.0.44/node_modules/@larksuite/cli/bin/lark-cli", true, true)
-	}
-	got := u.DetectInstallMethod()
-	if got.Method != InstallPnpm {
-		t.Errorf("Method = %v, want InstallPnpm", got.Method)
-	}
-	if !got.PnpmAvailable {
-		t.Errorf("PnpmAvailable = false, want true")
-	}
-}
-
-func TestDetectInstallMethod_NpmVsManual(t *testing.T) {
-	if m := detectFromResolved("/usr/local/lib/node_modules/@larksuite/cli/bin/lark-cli", true, false).Method; m != InstallNpm {
-		t.Errorf("npm path Method = %v, want InstallNpm", m)
-	}
-	if m := detectFromResolved("/usr/local/bin/lark-cli", false, false).Method; m != InstallManual {
-		t.Errorf("manual path Method = %v, want InstallManual", m)
-	}
-}
-
-func TestCanAutoUpdate_Pnpm(t *testing.T) {
-	if !(DetectResult{Method: InstallPnpm, PnpmAvailable: true}).CanAutoUpdate() {
-		t.Error("pnpm available should CanAutoUpdate")
-	}
-	if (DetectResult{Method: InstallPnpm, PnpmAvailable: false}).CanAutoUpdate() {
-		t.Error("pnpm unavailable should not CanAutoUpdate")
-	}
-}
-
-func TestManualReason_Pnpm(t *testing.T) {
-	if got := (DetectResult{Method: InstallPnpm, NpmAvailable: false, PnpmAvailable: false}).ManualReason(); got != "installed via pnpm, but pnpm is not available in PATH" {
-		t.Errorf("pnpm reason = %q", got)
-	}
-	if got := (DetectResult{Method: InstallManual}).ManualReason(); got != "not installed via npm or pnpm" {
-		t.Errorf("manual reason = %q", got)
-	}
-}
-
-func TestRunPnpmInstall_Override(t *testing.T) {
-	u := &Updater{PnpmInstallOverride: func(version string) *NpmResult {
-		r := &NpmResult{}
-		r.Stdout.WriteString("added @larksuite/cli@" + version)
-		return r
-	}}
-	got := u.RunPnpmInstall("2.0.0")
-	if got.Err != nil {
-		t.Fatalf("unexpected err: %v", got.Err)
-	}
-	if !strings.Contains(got.CombinedOutput(), "2.0.0") {
-		t.Errorf("output = %q, want version echoed", got.CombinedOutput())
-	}
-}
-
-func TestRunPnpmInstall_Error(t *testing.T) {
-	wantErr := errors.New("boom")
-	u := &Updater{PnpmInstallOverride: func(string) *NpmResult { return &NpmResult{Err: wantErr} }}
-	if got := u.RunPnpmInstall("2.0.0"); !errors.Is(got.Err, wantErr) {
-		t.Errorf("err = %v, want %v", got.Err, wantErr)
-	}
-}
-
-func TestSkillsInvocation(t *testing.T) {
-	addArgs := []string{"-y", "skills", "add", "https://open.feishu.cn", "-g", "-y"}
-	cases := []struct {
-		name          string
-		method        InstallMethod
-		pnpmAvailable bool
-		args          []string
-		wantLauncher  string
-		wantRest      []string
-	}{
-		{"pnpm install + pnpm available → pnpm dlx, drop leading -y", InstallPnpm, true, addArgs,
-			"pnpm", []string{"dlx", "skills", "add", "https://open.feishu.cn", "-g", "-y"}},
-		{"pnpm install but pnpm unavailable → npx unchanged", InstallPnpm, false, addArgs,
-			"npx", addArgs},
-		{"npm install → npx unchanged", InstallNpm, false, addArgs,
-			"npx", addArgs},
-		{"manual install → npx unchanged", InstallManual, false, []string{"-y", "skills", "ls", "-g"},
-			"npx", []string{"-y", "skills", "ls", "-g"}},
-		{"pnpm without a leading -y → prepend dlx only", InstallPnpm, true, []string{"skills", "ls", "-g"},
-			"pnpm", []string{"dlx", "skills", "ls", "-g"}},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			gotLauncher, gotRest := skillsInvocation(c.method, c.pnpmAvailable, c.args)
-			if gotLauncher != c.wantLauncher {
-				t.Errorf("launcher = %q, want %q", gotLauncher, c.wantLauncher)
-			}
-			if strings.Join(gotRest, " ") != strings.Join(c.wantRest, " ") {
-				t.Errorf("rest = %v, want %v", gotRest, c.wantRest)
-			}
-		})
-	}
-}
-
-// TestDetectInstallMethod_Caches locks the fix for the post-update re-detection
-// hazard: DetectInstallMethod must return the first (pre-update) detection on
-// subsequent calls, so the skills launcher chosen after the binary is replaced
-// stays consistent with what was detected — and reported — before the update.
-func TestDetectInstallMethod_Caches(t *testing.T) {
-	u := New()
-	cached := DetectResult{Method: InstallPnpm, PnpmAvailable: true, ResolvedPath: "/x/pnpm/store/v11/links/@larksuite/cli/1.0.0/node_modules/@larksuite/cli/bin/lark-cli"}
-	u.detectCache = &cached
-	got := u.DetectInstallMethod()
-	if got.Method != InstallPnpm || !got.PnpmAvailable {
-		t.Errorf("expected cached pnpm result to be returned, got %+v", got)
-	}
-}
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@larksuite/cli",
-  "version": "1.0.66",
+  "version": "1.0.65",
  "description": "The official CLI for Lark/Feishu open platform",
  "bin": {
    "lark-cli": "scripts/run.js"
--- a/skills/lark-doc/references/style/lark-doc-create-workflow.md
+++ b/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。若执行了专项校验，向用户呈现结果
--- a/skills/lark-shared/SKILL.md
+++ b/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: use `--profile <profile-or-appId>` for one command; for a task/session, prefix later `lark-cli` commands with `LARKSUITE_CLI_PROFILE=<profile-or-appId>` unless shell env persists, where you may `export` once and later `unset`. Ask if the selector is unknown; do not merely promise. Use `whoami` for the effective app/profile identity and `auth status --json --verify` for OAuth token state. Do not run `lark-cli profile use` unless changing the long-term default, and 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）到终端明文。
--- a/skills/lark-task/references/lark-task-create.md
+++ b/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.
Author	SHA1	Message	Date
luozhixiong	425122e611	fix(credential): propagate malformed-config error for explicit profile When an explicit profile was requested and LoadMultiAppConfig failed, the error was discarded and every failure reported as profile_not_found, masking a real config problem (e.g. malformed file) behind a misleading "run profile list" hint. Propagate the underlying error when it is a malformed-config failure (errors.Is ErrMalformedConfig) so errors.Is / errors.Unwrap keep working, mirroring the no-profile branch. An absent config is not malformed and still yields the friendly profile_not_found.	2026-07-07 15:33:44 +08:00
luozhixiong	80fade789b	docs(lark-shared): refine profile-selection guidance Clarify that --profile and LARKSUITE_CLI_PROFILE accept either a profile name or an app_id, keep the effective-identity vs OAuth-token boundary (whoami vs auth status --json --verify), and note not to set direct app-credential env vars unless direct credentials are provided.	2026-07-07 14:47:16 +08:00
luozhixiong	cc5cec32dc	test(credential): use recognized placeholders for secret fixtures Replace credential-shaped literals in whoami and selection tests with placeholder values recognized by the public-content quality gate (test-secret / your-secret / your-password / your-access-token), so the deterministic public-content scan does not flag test fixtures as generic credentials. No behavioral change; the fixtures are only compared for non-leakage and identity arbitration.	2026-07-07 14:47:16 +08:00
luozhixiong	251de0f609	docs: require auth status --json --verify for login/token checks	2026-07-07 11:28:13 +08:00
luozhixiong	d7156b327e	docs: point to auth status --json --verify for token validity checks	2026-07-07 11:27:34 +08:00
luozhixiong	a3c97572b6	docs: guide per-command LARKSUITE_CLI_PROFILE prefix for non-persistent shells	2026-07-07 11:22:54 +08:00
luozhixiong	978b711663	feat: distinguish auth status from whoami identity in help and skill	2026-07-06 20:53:24 +08:00
luozhixiong	d22d8473a2	docs: use imperative one-line whoami vs auth status routing boundary	2026-07-06 20:40:58 +08:00
luozhixiong	4c94bdca27	docs: clarify whoami vs auth status boundary in lark-shared profile rule	2026-07-06 20:32:39 +08:00
luozhixiong	29d5b95971	docs: trim lark-shared profile rule to lark-cli scope, drop agent-shell env mechanics	2026-07-06 20:23:34 +08:00
luozhixiong	fec11926be	docs: broaden lark-shared trigger to profile selection and add session-env persistence guidance	2026-07-06 20:16:01 +08:00
luozhixiong	816a6939f2	docs: forbid hollow identity promises in lark-shared profile hint	2026-07-06 20:02:42 +08:00
luozhixiong	04edca5717	fix(credential): add credential_source to config errors and report profile_secret_invalid for broken default secret	2026-07-06 19:27:04 +08:00
luozhixiong	a90715f5a9	docs: add profile selection entry hint to lark-shared skill	2026-07-06 18:13:21 +08:00
luozhixiong	f13cee23a2	docs: add profile selection help to profile and whoami commands	2026-07-06 18:10:32 +08:00
luozhixiong	e3cea8936e	refactor: drop whoami suggestion field and IdentitySelection.Suggestion whoami reports facts about the effective identity; it should not proactively push profile-switching guidance at agents. That guidance lives in `profile --help` / the lark-shared skill, and failure recovery already lives in error hints. Remove the now-unused Suggestion field from IdentitySelection and its only setter/consumer.	2026-07-06 18:05:24 +08:00
luozhixiong	f91e8bec54	feat: surface credentialSource and directCredentialEnv in whoami	2026-07-06 18:01:02 +08:00
luozhixiong	0c5aae42b4	test(credential): lock profile_secret_invalid against secret-bearing cause Add a case where the underlying account-resolution error itself contains a secret marker, proving doResolveAccount's drop-the-cause design (§5.1) holds beyond the existing noop-keychain (empty-error) test, including across the full errors.Unwrap chain.	2026-07-06 17:52:03 +08:00
luozhixiong	bf8c41225d	fix(credential): gate success-account direct-credential treatment on env provider Mirror the env-incomplete block-path guard on the success-account path so a non-env extension provider (e.g. sidecar, Priority 0) that returns an account wins outright instead of being misreported as a direct-credential env account. This restores pre-diff behavior for such providers: no profile arbitration, no spurious profile_app_credential_conflict, and DirectCredentialEnv.Present stays false when no direct env vars are set. Env matrix states are unchanged. Add TestSelection_NonEnvExtensionProviderWinsOverProfile as a regression guard.	2026-07-06 17:42:16 +08:00
luozhixiong	0c51792f77	feat: unify credential selection with profile conflict detection	2026-07-06 17:30:51 +08:00
luozhixiong	e30869d015	feat: add IdentitySelection type for explainable credential selection	2026-07-06 17:17:40 +08:00
luozhixiong	a3e78daff9	feat: add profile selection error subtypes and machine-readable fields Declares the 5 stable error subtypes (4 config + 1 validation) and the ConfigError/ValidationError extension fields the profile-selection credential core (Task 4) will produce, plus builder-chain and wire-pin tests pinning their shape.	2026-07-06 17:12:56 +08:00
luozhixiong	8abd39b18e	feat: add LARKSUITE_CLI_PROFILE session env with flag precedence Add LARKSUITE_CLI_PROFILE env var and make BootstrapInvocationContext fall back to it when --profile is empty, so downstream credential resolution sees the correct profile. Also track whether the resolved profile came from the flag or the env fallback via a new InvocationContext.ProfileFromFlag field, needed by a later task to report the correct credential source.	2026-07-06 17:06:12 +08:00