feat(auth): support managed external credentials

Add Extended-only direct, credential-proxy, and platform-proxy modes while keeping Standard behavior and external-credential product details isolated behind source-neutral runtime capabilities.

Fail closed across helper execution, proxy routing, streams, managed file transfers, and unsupported event flows. Harden system configuration, edition updates, and release publication.

Cover Standard compatibility and Extended integration with contract tests, repository-local three-mode E2E, native trust checks, and CI and release gates.

.github/workflows/ci.yml

@@ -82,6 +82,56 @@ jobs:
       - name: Run sidecar tag build + HMAC round-trip
         run: make sidecar-test
 
+  extended-integration:
+    needs: fast-gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: '3.x'
+      - name: Fetch meta data
+        run: python3 scripts/fetch_meta.py
+      - name: Build both editions and verify identity
+        run: |
+          set -euo pipefail
+          go build -o /tmp/lark-cli-standard .
+          go build -tags extended -o /tmp/lark-cli-extended .
+          test "$(/tmp/lark-cli-standard version --json | jq -r .edition)" = "standard"
+          test "$(/tmp/lark-cli-extended version --json | jq -r .edition)" = "extended"
+          test "$(/tmp/lark-cli-extended version --json | jq -r '.capabilities[]')" = "external-credential-platform"
+      - name: Cross-compile Extended platform-specific security code
+        run: |
+          set -euo pipefail
+          GOOS=darwin GOARCH=arm64 go build -tags extended -o /tmp/lark-cli-extended-darwin .
+          GOOS=windows GOARCH=amd64 go build -tags extended -o /tmp/lark-cli-extended-windows.exe .
+      - name: Verify edition source isolation
+        run: go test -count=1 ./internal/externalcredential -run '^TestEditionSourceIsolation$'
+      - name: Run Extended tests
+        run: make extended-test
+
+  extended-platform-security:
+    needs: fast-gate
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version-file: go.mod
+      - name: Run native helper isolation and path trust tests
+        run: go test -tags extended -count=1 ./internal/externalcredential -run '^(TestNativeAdminControlledPath|TestCredentialProcessEnvironmentUsesExplicitAllowlist|TestCredentialProcessCommandRunsWithIsolatedEnvironment)$'
+
   # ── Layer 2: Quality Gate ──────────────────────────────────────────
   unit-test:
     needs: fast-gate
@@ -142,6 +192,28 @@ jobs:
           node-version: '22'
       - name: Run script tests
         run: make script-test
+      - name: Install GoReleaser
+        uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
+        with:
+          version: '~> v2'
+          install-only: true
+      - name: Validate GoReleaser configuration
+        run: goreleaser check
+      - name: Check Extended installer syntax
+        shell: pwsh
+        run: |
+          sh -n scripts/install-extended.sh
+          $tokens = $null
+          $errors = $null
+          [System.Management.Automation.Language.Parser]::ParseFile(
+            (Resolve-Path scripts/install-extended.ps1),
+            [ref]$tokens,
+            [ref]$errors
+          ) | Out-Null
+          if ($errors.Count -ne 0) {
+            $errors | ForEach-Object { Write-Error $_ }
+            exit 1
+          }
 
   deterministic-gate:
     needs: fast-gate
@@ -216,16 +288,20 @@ jobs:
           # second time here — and, crucially, so an observe-only suite's failure
           # can never block merges through coverage's spot in the results loop.
           packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/')
-          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
+          go test -race -coverprofile=coverage-standard.txt -covermode=atomic $packages
+          # Extended implementation files are selected by build tags and would
+          # otherwise be absent from the uploaded report. Their race-enabled
+          # suite runs in extended-integration; this pass contributes coverage.
+          go test -tags extended -coverprofile=coverage-extended.txt -covermode=atomic $packages
       - name: Upload coverage to Codecov
         if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
         uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
         with:
-          files: coverage.txt
+          files: coverage-standard.txt,coverage-extended.txt
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Check coverage threshold
         run: |
-          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}' | tr -d '%')
+          total=$(go tool cover -func=coverage-standard.txt | grep total | awk '{print $3}' | tr -d '%')
           threshold=40
           echo "Coverage: ${total}% (threshold: ${threshold}%)"
           if (( $(echo "$total < $threshold" | bc -l) )); then
@@ -235,21 +311,31 @@ jobs:
       - name: Coverage summary
         if: ${{ !cancelled() }}
         run: |
-          if [ ! -f coverage.txt ]; then
-            echo "No coverage data available" >> $GITHUB_STEP_SUMMARY
-            exit 0
-          fi
-          total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
           echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
-          echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
-          echo '```' >> $GITHUB_STEP_SUMMARY
-          echo "</details>" >> $GITHUB_STEP_SUMMARY
+          report_coverage() {
+            profile="$1"
+            label="$2"
+            echo "### ${label} edition" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            if [ ! -f "$profile" ]; then
+              echo "No ${label} coverage data available." >> $GITHUB_STEP_SUMMARY
+              echo "" >> $GITHUB_STEP_SUMMARY
+              return
+            fi
+            total=$(go tool cover -func="$profile" | grep total | awk '{print $3}')
+            echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "<details><summary>Details</summary>" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            go tool cover -func="$profile" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "</details>" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+          }
+          report_coverage coverage-standard.txt Standard
+          report_coverage coverage-extended.txt Extended
 
   deadcode:
     needs: fast-gate
@@ -520,7 +606,7 @@ jobs:
   # ── Results Gate (single required check for branch protection) ─────
   results:
     if: ${{ always() }}
-    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header, plugin-integration, sidecar-integration]
+    needs: [fast-gate, unit-test, lint, script-test, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header, plugin-integration, sidecar-integration, extended-integration, extended-platform-security]
     runs-on: ubuntu-latest
     steps:
       - name: Evaluate results
@@ -542,6 +628,8 @@ jobs:
           echo "| L4 | license-header | ${{ needs.license-header.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L4 | plugin-integration (observe-only) | ${{ needs.plugin-integration.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L4 | sidecar-integration (observe-only) | ${{ needs.sidecar-integration.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | extended-integration | ${{ needs.extended-integration.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| L4 | extended-platform-security | ${{ needs.extended-platform-security.result }} |" >> $GITHUB_STEP_SUMMARY
 
           # Any failure or cancellation in any job blocks the merge.
           # Legitimately skipped jobs (deadcode on push, e2e-live when not
@@ -565,7 +653,9 @@ jobs:
             "${{ needs.e2e-dry-run.result }}" \
             "${{ needs.e2e-live.result }}" \
             "${{ needs.security.result }}" \
-            "${{ needs.license-header.result }}"; do
+            "${{ needs.license-header.result }}" \
+            "${{ needs.extended-integration.result }}" \
+            "${{ needs.extended-platform-security.result }}"; do
             if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
               FAILED=1
             fi

.github/workflows/release.yml

@@ -46,6 +46,8 @@ jobs:
     runs-on: ubuntu-22.04
     permissions:
       contents: write
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
@@ -68,7 +70,7 @@ jobs:
       - name: Install pinned npm
         run: npm install --global npm@11.16.0
 
-      - name: Run GoReleaser
+      - name: Build and upload draft release with GoReleaser
         uses: goreleaser/goreleaser-action@e435ccd777264be153ace6237001ef4d979d3a7a # v6
         with:
           version: '~> v2'
@@ -80,14 +82,41 @@ jobs:
         run: |
           set -euo pipefail
           test -s dist/checksums.txt
+          cp scripts/install-extended.sh scripts/install-extended.ps1 dist/
           (cd dist && sha256sum --check checksums.txt)
           cp dist/checksums.txt checksums.txt
 
+      - name: Verify release edition identities
+        run: |
+          set -euo pipefail
+          mkdir -p /tmp/lark-cli-standard /tmp/lark-cli-extended
+          tar -xzf "dist/lark-cli-${GITHUB_REF_NAME#v}-linux-amd64.tar.gz" -C /tmp/lark-cli-standard lark-cli
+          tar -xzf "dist/lark-cli-extended-${GITHUB_REF_NAME#v}-linux-amd64.tar.gz" -C /tmp/lark-cli-extended lark-cli
+          test "$(/tmp/lark-cli-standard/lark-cli version --json | jq -r .edition)" = "standard"
+          test "$(/tmp/lark-cli-extended/lark-cli version --json | jq -r .edition)" = "extended"
+          test "$(/tmp/lark-cli-standard/lark-cli version --json | jq -r .version)" = "${GITHUB_REF_NAME#v}"
+          test "$(/tmp/lark-cli-extended/lark-cli version --json | jq -r .version)" = "${GITHUB_REF_NAME#v}"
+
+      - name: Verify release platform asset matrix
+        run: bash scripts/verify-release-assets.sh dist "${GITHUB_REF_NAME#v}"
+
+      - name: Attest release archives
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2
+        with:
+          subject-path: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/checksums.txt
+            dist/install-extended.sh
+            dist/install-extended.ps1
+
       - name: Collect release asset
         run: |
           set -euo pipefail
           mkdir npm-publish-asset
-          cp dist/*.tar.gz dist/*.zip dist/checksums.txt npm-publish-asset/
+          cp dist/*.tar.gz dist/*.zip dist/checksums.txt \
+            dist/install-extended.sh dist/install-extended.ps1 \
+            npm-publish-asset/
 
       - name: Upload release asset
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
@@ -97,6 +126,76 @@ jobs:
           if-no-files-found: error
           overwrite: true
 
+      - name: Publish verified GitHub release
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            const crypto = require("node:crypto");
+            const fs = require("node:fs");
+            const tag = process.env.RELEASE_TAG;
+            const { owner, repo } = context.repo;
+            const releases = await github.paginate(github.rest.repos.listReleases, {
+              owner,
+              repo,
+              per_page: 100,
+            });
+            const matches = releases.filter((release) => release.tag_name === tag);
+            if (matches.length !== 1) {
+              throw new Error(`expected exactly one draft release for ${tag}, found ${matches.length}`);
+            }
+            const release = matches[0];
+            if (!release.draft) {
+              throw new Error(`release ${tag} became public before verification completed`);
+            }
+
+            const checksumPath = "dist/checksums.txt";
+            const checksumBody = fs.readFileSync(checksumPath, "utf8");
+            const expectedDigests = new Map();
+            for (const line of checksumBody.split(/\r?\n/)) {
+              if (!line.trim()) continue;
+              const match = line.match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+              if (!match) throw new Error(`invalid checksums.txt line: ${line}`);
+              const name = match[2];
+              if (expectedDigests.has(name)) {
+                throw new Error(`duplicate checksums.txt entry: ${name}`);
+              }
+              expectedDigests.set(name, `sha256:${match[1].toLowerCase()}`);
+            }
+            expectedDigests.set(
+              "checksums.txt",
+              `sha256:${crypto.createHash("sha256").update(checksumBody).digest("hex")}`,
+            );
+
+            const actualNames = release.assets.map((asset) => asset.name).sort();
+            const expectedNames = [...expectedDigests.keys()].sort();
+            if (JSON.stringify(actualNames) !== JSON.stringify(expectedNames)) {
+              throw new Error(
+                `draft release asset set mismatch: expected ${expectedNames.join(", ")}, got ${actualNames.join(", ")}`,
+              );
+            }
+            for (const asset of release.assets) {
+              const expected = expectedDigests.get(asset.name);
+              if (!asset.digest) {
+                throw new Error(`GitHub did not report a digest for draft asset ${asset.name}`);
+              }
+              if (asset.digest.toLowerCase() !== expected) {
+                throw new Error(
+                  `draft asset digest mismatch for ${asset.name}: expected ${expected}, got ${asset.digest}`,
+                );
+              }
+            }
+
+            await github.rest.repos.updateRelease({
+              owner,
+              repo,
+              release_id: release.id,
+              draft: false,
+              make_latest: "true",
+            });
+
   publish-npm:
     needs: build-release
     runs-on: ubuntu-22.04

.goreleaser.yml

@@ -5,7 +5,8 @@ before:
     - python3 scripts/fetch_meta.py
 
 builds:
-  - binary: lark-cli
+  - id: standard
+    binary: lark-cli
     env:
       - CGO_ENABLED=0
     ldflags:
@@ -18,12 +19,54 @@ builds:
       - amd64
       - arm64
       - riscv64
+    ignore:
+      - goos: darwin
+        goarch: riscv64
+      - goos: windows
+        goarch: riscv64
+  - id: extended
+    binary: lark-cli
+    tags:
+      - extended
+    env:
+      - CGO_ENABLED=0
+    ldflags:
+      - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
+    goos:
+      - darwin
+      - linux
+      - windows
+    goarch:
+      - amd64
+      - arm64
+      - riscv64
+    ignore:
+      - goos: darwin
+        goarch: riscv64
+      - goos: windows
+        goarch: riscv64
 
 archives:
-  - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
+  - id: standard
+    ids:
+      - standard
+    name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
     format_overrides:
       - goos: windows
-        format: zip
+        formats:
+          - zip
+    files:
+      - README.md
+      - LICENSE
+      - CHANGELOG.md
+  - id: extended
+    ids:
+      - extended
+    name_template: "lark-cli-extended-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
+    format_overrides:
+      - goos: windows
+        formats:
+          - zip
     files:
       - README.md
       - LICENSE
@@ -31,6 +74,18 @@ archives:
 
 checksum:
   name_template: checksums.txt
+  extra_files:
+    - glob: ./scripts/install-extended.sh
+    - glob: ./scripts/install-extended.ps1
+
+release:
+  # Keep assets undiscoverable by releases/latest until the workflow has
+  # independently verified checksums, edition identity, and platform coverage.
+  draft: true
+  replace_existing_draft: true
+  extra_files:
+    - glob: ./scripts/install-extended.sh
+    - glob: ./scripts/install-extended.ps1
 
 changelog:
   sort: asc

Makefile

@@ -23,7 +23,7 @@ PREFIX   ?= /usr/local
 TEST_GOARCH := $(or $(GOARCH),$(shell go env GOARCH))
 RACE_FLAG := $(if $(filter riscv64,$(TEST_GOARCH)),,-race)
 
-.PHONY: all build vet fmt-check script-test test unit-test live-skills-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks sidecar-test
+.PHONY: all build vet fmt-check script-test test unit-test live-skills-test integration-test examples-build quality-gate install uninstall clean fetch_meta gitleaks sidecar-test extended-test
 
 all: test
 
@@ -50,6 +50,7 @@ fmt-check:
 script-test:
 	bash scripts/resolve-changed-from.test.sh
 	bash scripts/ci-workflow.test.sh
+	bash scripts/release-workflow.test.sh
 	bash scripts/semantic-review-workflow.test.sh
 	$(NODE) --test scripts/e2e_domains.test.js scripts/fetch_e2e_tat.test.js scripts/install.test.js scripts/release-preflight.test.js scripts/semantic-review-verify-artifact.test.js scripts/pr-quality-summary.test.js scripts/semantic-review-publish.test.js scripts/ci-quality-summary-publish.test.js
 
@@ -121,6 +122,12 @@ sidecar-test:
 	go test $(RACE_FLAG) -count=1 -tags authsidecar_demo ./sidecar/server-demo/
 	go test $(RACE_FLAG) -count=1 -tags authsidecar ./tests/sidecar_e2e/
 
+# extended-test compiles and exercises the separately distributed Extended
+# edition. The default build remains the Standard npm/npx binary.
+extended-test:
+	go build -tags extended -o /dev/null .
+	go test $(RACE_FLAG) -count=1 -tags extended ./cmd/... ./internal/... ./shortcuts/... ./extension/... ./tests/externalcredential_e2e
+
 # Run secret-leak checks locally before pushing.
 # Step 1: check-doc-tokens catches realistic-looking example tokens in reference
 #         docs and asks you to use _EXAMPLE_TOKEN placeholders instead.

affordance/contact.md

@@ -23,6 +23,41 @@ lark-cli contact +search-user --query "alice" --as user
 lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
 ```
 
+## +search-bot
+Search bots (apps) by keyword. Pass `--query` or `--queries`; use `--chat-ids` to search within specific chats.
+
+### Skills
+- lark-contact/references/lark-contact-search-bot.md
+
+### Avoid when
+- Looking for a person rather than a bot → use [[+search-user]]
+- Running as a bot — this shortcut is user-only
+
+### Tips
+- `has_more=true` means the search is incomplete; refine the keyword or search scope instead of paginating
+
+### Examples
+
+**Find bots by keyword**
+```bash
+lark-cli contact +search-bot --query "会议助手" --as user
+```
+
+**Search inside one chat**
+```bash
+lark-cli contact +search-bot --query "助手" --chat-ids "oc_3a8b****6a7b" --as user
+```
+
+**Find bots you've chatted with**
+```bash
+lark-cli contact +search-bot --query "助手" --has-chatted --as user
+```
+
+**Search several bot keywords in one call**
+```bash
+lark-cli contact +search-bot --queries "会议助手,日报助手,审批助手" --as user
+```
+
 ## +get-user
 Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
 

affordance/docs.md

@@ -1,38 +0,0 @@
-# docs
-> skill: lark-doc
-
-## +create
-Create a document from XML or Markdown content.
-
-### Skills
-- lark-doc/references/lark-doc-create.md
-
-## +fetch
-Fetch a document or a focused portion of its content.
-
-### Skills
-- lark-doc/references/lark-doc-fetch.md
-
-## +update
-Update document content with a supported document command.
-
-### Skills
-- lark-doc/references/lark-doc-update.md
-
-## +history-list
-List document history versions.
-
-### Skills
-- lark-doc/references/lark-doc-history.md
-
-## +history-revert
-Revert a document to a history version.
-
-### Skills
-- lark-doc/references/lark-doc-history.md
-
-## +history-revert-status
-Check the status of a document history revert.
-
-### Skills
-- lark-doc/references/lark-doc-history.md

cmd/auth/auth.go

@@ -18,21 +18,11 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/recovery"
+	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 // NewCmdAuth creates the auth command with subcommands.
 func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
-	return newCmdAuth(f, nil)
-}
-
-// NewCmdAuthWithRecovery creates the auth command with a build-local recovery
-// presenter while preserving NewCmdAuth's established function signature.
-func NewCmdAuthWithRecovery(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
-	return newCmdAuth(f, projector)
-}
-
-func newCmdAuth(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
 		Short: "OAuth credentials and authorization management",
@@ -41,21 +31,23 @@ func newCmdAuth(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Comman
 			// PersistentPreRun[E] found walking up the chain, so the root-level
 			// SilenceUsage=true would be skipped without this line.
 			cmd.SilenceUsage = true
-			// cmd.Name() returns the subcommand name (e.g. "login"), not "auth".
-			// Pass "auth" as a literal so the error message reads
-			// `"auth" is not supported: ...`
-			return f.RequireBuiltinCredentialProvider(cmd.Context(), "auth")
+			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalCredentialManagement)
 
-	cmd.AddCommand(NewCmdAuthLogin(f, nil))
-	cmd.AddCommand(NewCmdAuthLogout(f, nil))
-	cmd.AddCommand(newCmdAuthStatus(f, nil, projector))
-	cmd.AddCommand(NewCmdAuthScopes(f, nil))
-	cmd.AddCommand(newCmdAuthList(f, nil, projector))
-	cmd.AddCommand(newCmdAuthCheck(f, nil, projector))
-	cmd.AddCommand(NewCmdAuthQRCode(f, nil))
+	login := NewCmdAuthLogin(f, nil)
+	logout := NewCmdAuthLogout(f, nil)
+	status := NewCmdAuthStatus(f, nil)
+	scopes := NewCmdAuthScopes(f, nil)
+	list := NewCmdAuthList(f, nil)
+	check := NewCmdAuthCheck(f, nil)
+	qrcode := NewCmdAuthQRCode(f, nil)
+	for _, diagnostic := range []*cobra.Command{status, scopes, check, qrcode} {
+		cmdutil.SetRuntimeCapabilities(diagnostic)
+	}
+	cmd.AddCommand(login, logout, status, scopes, list, check, qrcode)
 	return cmd
 }
 

cmd/auth/auth_test.go

@@ -530,10 +530,7 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 	}{
 		{"login", []string{"login"}},
 		{"logout", []string{"logout"}},
-		{"status", []string{"status"}},
-		{"check", []string{"check", "--scope", "calendar:read"}}, // --scope is required
 		{"list", []string{"list"}},
-		{"scopes", []string{"scopes"}},
 	}
 
 	for _, tt := range tests {
@@ -558,3 +555,19 @@ func TestAuthBlockedByExternalProvider(t *testing.T) {
 		})
 	}
 }
+
+func TestAuthReadOnlyCommandsAllowedByExternalProvider(t *testing.T) {
+	f := newFactoryWithExternalProvider(t)
+	for _, name := range []string{"status", "check", "scopes", "qrcode"} {
+		t.Run(name, func(t *testing.T) {
+			cmd := NewCmdAuth(f)
+			matched, _, err := cmd.Find([]string{name})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if err := cmd.PersistentPreRunE(matched, nil); err != nil {
+				t.Fatalf("read-only command blocked: %v", err)
+			}
+		})
+	}
+}

cmd/auth/check.go

@@ -4,6 +4,7 @@
 package auth
 
 import (
+	"context"
 	"fmt"
 	"strings"
 
@@ -12,8 +13,8 @@ import (
 	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // CheckOptions holds all inputs for auth check.
@@ -25,14 +26,6 @@ type CheckOptions struct {
 
 // NewCmdAuthCheck creates the auth check subcommand.
 func NewCmdAuthCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.Command {
-	return newCmdAuthCheck(f, runF, nil)
-}
-
-func newCmdAuthCheck(
-	f *cmdutil.Factory,
-	runF func(*CheckOptions) error,
-	projector *recovery.Projector,
-) *cobra.Command {
 	opts := &CheckOptions{Factory: f}
 
 	cmd := &cobra.Command{
@@ -42,7 +35,7 @@ func newCmdAuthCheck(
 			if runF != nil {
 				return runF(opts)
 			}
-			return authCheckRunWithRecovery(opts, projector)
+			return authCheckRunContext(cmd.Context(), opts)
 		},
 	}
 
@@ -55,10 +48,10 @@ func newCmdAuthCheck(
 }
 
 func authCheckRun(opts *CheckOptions) error {
-	return authCheckRunWithRecovery(opts, nil)
+	return authCheckRunContext(context.Background(), opts)
 }
 
-func authCheckRunWithRecovery(opts *CheckOptions, projector *recovery.Projector) error {
+func authCheckRunContext(ctx context.Context, opts *CheckOptions) error {
 	f := opts.Factory
 
 	required := strings.Fields(opts.Scope)
@@ -70,18 +63,74 @@ func authCheckRunWithRecovery(opts *CheckOptions, projector *recovery.Projector)
 	if err != nil {
 		return err
 	}
-	if config.UserOpenId == "" {
+	if f.Credential == nil {
+		return errs.NewInternalError(errs.SubtypeUnknown, "credential inspection is unavailable")
+	}
+
+	inspection, err := f.Credential.InspectToken(ctx, credential.TokenInspectionRequest{
+		TokenSpec: credential.TokenSpec{
+			Type:  credential.TokenTypeUAT,
+			AppID: config.AppID,
+		},
+		IncludeScopes: true,
+	})
+	if err != nil {
+		if _, ok := errs.ProblemOf(err); ok {
+			return err
+		}
+		return errs.NewInternalError(errs.SubtypeUnknown,
+			"failed to inspect user authorization: %v", err).
+			WithCause(err)
+	}
+	if inspection == nil {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"credential source returned no authorization inspection")
+	}
+
+	if inspection.Status == credential.TokenInspectionNotLoggedIn && !inspection.Source.Managed {
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": false, "error": "not_logged_in", "missing": required})
 		return output.ErrBare(1)
 	}
-
-	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
-	if stored == nil {
+	if !inspection.Present {
+		if inspection.Source.Managed {
+			return errs.NewAuthenticationError(errs.SubtypeTokenMissing,
+				"credential source %q did not provide a user access token", inspection.Source.Name).
+				WithHint("authorize the user through the selected credential source")
+		}
 		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"ok": false, "error": "no_token", "missing": required})
 		return output.ErrBare(1)
 	}
 
-	missing := larkauth.MissingScopes(stored.Scope, required)
+	switch inspection.ScopeState {
+	case credential.ScopeUnsupported:
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"auth check is unsupported by credential source %q because granted scopes are unavailable", inspection.Source.Name).
+			WithHint("the credential source must expose trusted scope metadata before `auth check` can evaluate --scope")
+	case credential.ScopeUnknown:
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"auth check result is unknown because credential source %q returned no scope metadata", inspection.Source.Name).
+			WithHint("configure the credential source to return trusted scopes for user access tokens")
+	case credential.ScopeKnown:
+		// Continue below.
+	default:
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"credential source %q returned invalid scope inspection state %q", inspection.Source.Name, inspection.ScopeState)
+	}
+
+	suggestion := ""
+	missing := larkauth.MissingScopes(inspection.Scopes, required)
+	if inspection.Source.Managed {
+		if len(missing) > 0 {
+			suggestion = fmt.Sprintf("grant these scopes through credential source %s: %s", inspection.Source.Name, strings.Join(missing, " "))
+		}
+	} else {
+		suggestion = fmt.Sprintf(`lark-cli auth login --scope "%s"`, strings.Join(missing, " "))
+	}
+	return writeAuthCheckResult(f, required, inspection.Scopes, suggestion)
+}
+
+func writeAuthCheckResult(f *cmdutil.Factory, required []string, availableScopes, suggestion string) error {
+	missing := larkauth.MissingScopes(availableScopes, required)
 	missingSet := make(map[string]bool, len(missing))
 	for _, s := range missing {
 		missingSet[s] = true
@@ -95,8 +144,8 @@ func authCheckRunWithRecovery(opts *CheckOptions, projector *recovery.Projector)
 
 	ok := len(missing) == 0
 	result := map[string]interface{}{"ok": ok, "granted": granted, "missing": missing}
-	if len(missing) > 0 && projector.CanReference(recovery.TargetAuthLogin) {
-		result["suggestion"] = fmt.Sprintf(`lark-cli auth login --scope "%s"`, strings.Join(missing, " "))
+	if len(missing) > 0 && suggestion != "" {
+		result["suggestion"] = suggestion
 	}
 	output.PrintJson(f.IOStreams.Out, result)
 	if !ok {

cmd/auth/check_test.go

@@ -4,18 +4,21 @@
 package auth
 
 import (
+	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"strings"
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
 	larkauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/zalando/go-keyring"
 )
 
@@ -149,6 +152,128 @@ func TestAuthCheckRun_ScopedTokenPresent_ExitZero(t *testing.T) {
 	}
 }
 
+type authCheckExternalProvider struct {
+	token        *extcred.Token
+	capabilities credential.ProviderCapabilities
+	resolveCalls int
+}
+
+func (p *authCheckExternalProvider) Name() string { return "external-check-test" }
+
+func (p *authCheckExternalProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
+	return &extcred.Account{AppID: "test-app", Brand: extcred.BrandFeishu}, nil
+}
+
+func (p *authCheckExternalProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
+	p.resolveCalls++
+	return p.token, nil
+}
+
+func (p *authCheckExternalProvider) CredentialCapabilities() credential.ProviderCapabilities {
+	return p.capabilities
+}
+
+func externalAuthCheckFactory(t *testing.T, canInspectScopes bool, token *extcred.Token) (*cmdutil.Factory, *authCheckExternalProvider) {
+	t.Helper()
+	cfg := &core.CliConfig{
+		AppID: "test-app",
+		Brand: core.BrandFeishu,
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, cfg)
+	provider := &authCheckExternalProvider{
+		token: token,
+		capabilities: credential.ProviderCapabilities{
+			ProvidesOnDemandAuth: true,
+			CanInspectScopes:     canInspectScopes,
+		},
+	}
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{provider},
+		nil,
+		nil,
+		nil,
+	)
+	return f, provider
+}
+
+func TestAuthCheckRun_ExternalDirectUsesProviderScopes(t *testing.T) {
+	f, provider := externalAuthCheckFactory(t, true, &extcred.Token{
+		Value:  "external-uat",
+		Scopes: "im:message docx:document",
+	})
+	stdout := f.IOStreams.Out.(*bytes.Buffer)
+
+	err := authCheckRun(&CheckOptions{
+		Factory: f,
+		Scope:   "im:message",
+	})
+	if err != nil {
+		t.Fatalf("authCheckRun() error = %v", err)
+	}
+	if provider.resolveCalls != 1 {
+		t.Fatalf("ResolveToken calls = %d, want 1", provider.resolveCalls)
+	}
+
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
+	}
+	if payload["ok"] != true {
+		t.Fatalf("stdout.ok = %v, want true; payload=%v", payload["ok"], payload)
+	}
+	granted, ok := payload["granted"].([]any)
+	if !ok || len(granted) != 1 || granted[0] != "im:message" {
+		t.Fatalf("stdout.granted = %v, want [im:message]", payload["granted"])
+	}
+}
+
+func TestAuthCheckRun_ExternalProxyReturnsTypedUnknown(t *testing.T) {
+	f, provider := externalAuthCheckFactory(t, false, &extcred.Token{
+		Value: "proxy-placeholder",
+	})
+
+	err := authCheckRun(&CheckOptions{
+		Factory: f,
+		Scope:   "im:message",
+	})
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %T %v, want typed error", err, err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("problem = %#v, want validation/failed_precondition", problem)
+	}
+	var validation *errs.ValidationError
+	if !errors.As(err, &validation) || !strings.Contains(problem.Message, "unsupported") || validation.Param != "" || problem.Hint == "" {
+		t.Fatalf("problem = %#v, want explicit unsupported result with actionable hint and no param", problem)
+	}
+	if provider.resolveCalls != 0 {
+		t.Fatalf("ResolveToken calls = %d, want 0 for proxy scope check", provider.resolveCalls)
+	}
+}
+
+func TestAuthCheckRun_ExternalDirectWithoutScopeMetadataReturnsTypedUnknown(t *testing.T) {
+	f, _ := externalAuthCheckFactory(t, true, &extcred.Token{
+		Value: "external-uat",
+	})
+
+	err := authCheckRun(&CheckOptions{
+		Factory: f,
+		Scope:   "im:message",
+	})
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %T %v, want typed error", err, err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("problem = %#v, want validation/failed_precondition", problem)
+	}
+	var validation *errs.ValidationError
+	if !errors.As(err, &validation) || !strings.Contains(problem.Message, "unknown") || validation.Param != "" || problem.Hint == "" {
+		t.Fatalf("problem = %#v, want explicit unknown result with actionable hint and no param", problem)
+	}
+}
+
 func TestAuthCheckRun_EmptyScopeIsValidationError(t *testing.T) {
 	// Scope validation is a real input error, not a predicate negative
 	// answer — it must surface as a typed ValidationError with the normal
@@ -165,70 +290,3 @@ func TestAuthCheckRun_EmptyScopeIsValidationError(t *testing.T) {
 		t.Errorf("exit code = %d, want ExitValidation (%d)", got, output.ExitValidation)
 	}
 }
-
-func TestAuthCheckRun_ConcealedLoginOmitsSuggestion(t *testing.T) {
-	keyring.MockInit()
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_DATA_DIR", t.TempDir())
-
-	cfg := &core.CliConfig{
-		AppID:      "test-app",
-		AppSecret:  "test-secret",
-		Brand:      core.BrandFeishu,
-		UserOpenId: "ou_user",
-		UserName:   "tester",
-	}
-	now := time.Now()
-	if err := larkauth.SetStoredToken(&larkauth.StoredUAToken{
-		AppId:            cfg.AppID,
-		UserOpenId:       cfg.UserOpenId,
-		AccessToken:      "user-access-token",
-		RefreshToken:     "refresh-token",
-		ExpiresAt:        now.Add(time.Hour).UnixMilli(),
-		RefreshExpiresAt: now.Add(24 * time.Hour).UnixMilli(),
-		GrantedAt:        now.Add(-time.Hour).UnixMilli(),
-		Scope:            "im:message",
-	}); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-
-	visibleFactory, visibleStdout, _, _ := cmdutil.TestFactory(t, cfg)
-	if err := authCheckRun(&CheckOptions{
-		Factory: visibleFactory,
-		Scope:   "calendar:calendar:read",
-	}); output.ExitCodeOf(err) != 1 {
-		t.Fatalf("default check exit = %d, want predicate miss exit 1", output.ExitCodeOf(err))
-	}
-	var visiblePayload map[string]any
-	if err := json.Unmarshal(visibleStdout.Bytes(), &visiblePayload); err != nil {
-		t.Fatalf("default stdout must be valid JSON: %v", err)
-	}
-	if suggestion, _ := visiblePayload["suggestion"].(string); !strings.Contains(suggestion, "auth login") {
-		t.Fatalf("default output lost established login suggestion: %#v", visiblePayload)
-	}
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, cfg)
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandAuthLogin: surface.CommandConcealed,
-	})
-	err := authCheckRunWithRecovery(
-		&CheckOptions{Factory: f, Scope: "calendar:calendar:read"},
-		recovery.NewProjector(func() *surface.Plan { return plan }),
-	)
-	if got := output.ExitCodeOf(err); got != 1 {
-		t.Fatalf("exit code = %d, want predicate miss exit 1", got)
-	}
-	if stderr.Len() != 0 {
-		t.Fatalf("stderr must stay empty, got:\n%s", stderr.String())
-	}
-	var payload map[string]any
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("stdout must be valid JSON: %v\nstdout=%s", err, stdout.String())
-	}
-	if _, ok := payload["suggestion"]; ok {
-		t.Fatalf("concealed auth/login left a dead suggestion: %#v", payload["suggestion"])
-	}
-	if missing, ok := payload["missing"].([]any); !ok || len(missing) != 1 {
-		t.Fatalf("projection removed missing-scope facts: %#v", payload["missing"])
-	}
-}

cmd/auth/list.go

@@ -14,7 +14,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // ListOptions holds all inputs for auth list.
@@ -25,14 +24,6 @@ type ListOptions struct {
 
 // NewCmdAuthList creates the auth list subcommand.
 func NewCmdAuthList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Command {
-	return newCmdAuthList(f, runF, nil)
-}
-
-func newCmdAuthList(
-	f *cmdutil.Factory,
-	runF func(*ListOptions) error,
-	projector *recovery.Projector,
-) *cobra.Command {
 	opts := &ListOptions{Factory: f}
 
 	cmd := &cobra.Command{
@@ -42,7 +33,7 @@ func newCmdAuthList(
 			if runF != nil {
 				return runF(opts)
 			}
-			return authListRunWithRecovery(opts, projector)
+			return authListRun(opts)
 		},
 	}
 	cmd.Flags().BoolVar(&opts.JSON, "json", false, "structured JSON output")
@@ -52,10 +43,6 @@ func newCmdAuthList(
 }
 
 func authListRun(opts *ListOptions) error {
-	return authListRunWithRecovery(opts, nil)
-}
-
-func authListRunWithRecovery(opts *ListOptions, projector *recovery.Projector) error {
 	f := opts.Factory
 
 	multi, _ := core.LoadMultiAppConfig()
@@ -74,7 +61,7 @@ func authListRunWithRecovery(opts *ListOptions, projector *recovery.Projector) e
 		// workspace-aware, so we pull the message+hint out of
 		// NotConfiguredError() instead of hard-coding it.
 		var cfgErr *errs.ConfigError
-		if errors.As(projector.Render(core.NotConfiguredError()), &cfgErr) {
+		if errors.As(core.NotConfiguredError(), &cfgErr) {
 			fmt.Fprintln(f.IOStreams.ErrOut, cfgErr.Message)
 			if cfgErr.Hint != "" {
 				fmt.Fprintln(f.IOStreams.ErrOut, "  hint: "+cfgErr.Hint)
@@ -93,11 +80,7 @@ func authListRunWithRecovery(opts *ListOptions, projector *recovery.Projector) e
 			})
 			return nil
 		}
-		fmt.Fprint(f.IOStreams.ErrOut, "No logged-in users.")
-		if projector.CanReference(recovery.TargetAuthLogin) {
-			fmt.Fprint(f.IOStreams.ErrOut, " Run `lark-cli auth login` to log in.")
-		}
-		fmt.Fprintln(f.IOStreams.ErrOut)
+		fmt.Fprintln(f.IOStreams.ErrOut, "No logged-in users. Run `lark-cli auth login` to log in.")
 		return nil
 	}
 

cmd/auth/list_test.go

@@ -10,8 +10,6 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 )
 
 // TestAuthListRun_NotConfigured_ReturnsExitZero pins the contract that
@@ -128,49 +126,7 @@ func TestAuthListRun_DefaultMode_NoLoggedInUsers_KeepsTextOutput(t *testing.T) {
 	if stdout.Len() != 0 {
 		t.Errorf("stdout must stay empty in default mode, got:\n%s", stdout.String())
 	}
-	if got := stderr.String(); !strings.Contains(got, "No logged-in users") ||
-		!strings.Contains(got, "auth login") {
-		t.Errorf("stderr = %q, want established no-users login hint", got)
-	}
-}
-
-func TestAuthListRun_ConcealedLoginKeepsStateWithoutDeadRecovery(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	writeLogoutConfig(t, nil)
-
-	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandAuthLogin: surface.CommandConcealed,
-	})
-	if err := authListRunWithRecovery(
-		&ListOptions{Factory: f},
-		recovery.NewProjector(func() *surface.Plan { return plan }),
-	); err != nil {
-		t.Fatalf("auth list should remain a successful probe: %v", err)
-	}
-	if stdout.Len() != 0 {
-		t.Fatalf("stdout must stay empty, got:\n%s", stdout.String())
-	}
-	if got := stderr.String(); !strings.Contains(got, "No logged-in users") ||
-		strings.Contains(got, "auth login") {
-		t.Fatalf("concealed recovery = %q, want state without dead login action", got)
-	}
-}
-
-func TestAuthListRun_ConcealedConfigInitProjectsManualErrorOutput(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	f, _, stderr, _ := cmdutil.TestFactory(t, nil)
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandConfigInit: surface.CommandConcealed,
-	})
-	if err := authListRunWithRecovery(
-		&ListOptions{Factory: f},
-		recovery.NewProjector(func() *surface.Plan { return plan }),
-	); err != nil {
-		t.Fatalf("auth list should remain a successful probe: %v", err)
-	}
-	if got := stderr.String(); strings.Contains(got, "config init") {
-		t.Fatalf("manual config error rendering retained concealed recovery: %q", got)
+	if !strings.Contains(stderr.String(), "No logged-in users") {
+		t.Errorf("stderr = %q, want no-users hint", stderr.String())
 	}
 }

cmd/auth/qrcode.go

@@ -56,6 +56,7 @@ For ASCII output, the result is printed to stdout with fixed size.`,
 	cmd.Flags().IntVar(&opts.Size, "size", 256, "Size of the QR code image in pixels (default: 256, for PNG mode only)")
 	cmd.Flags().BoolVar(&opts.ASCII, "ascii", false, "Output ASCII QR code to stdout")
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "Output file path for PNG image (relative path within current directory, required for non-ASCII mode)")
+	cmdutil.SetRisk(cmd, "read")
 
 	return cmd
 }

cmd/auth/status.go

@@ -11,7 +11,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // StatusOptions holds all inputs for auth status.
@@ -23,14 +22,6 @@ type StatusOptions struct {
 
 // NewCmdAuthStatus creates the auth status subcommand.
 func NewCmdAuthStatus(f *cmdutil.Factory, runF func(*StatusOptions) error) *cobra.Command {
-	return newCmdAuthStatus(f, runF, nil)
-}
-
-func newCmdAuthStatus(
-	f *cmdutil.Factory,
-	runF func(*StatusOptions) error,
-	projector *recovery.Projector,
-) *cobra.Command {
 	opts := &StatusOptions{Factory: f}
 
 	cmd := &cobra.Command{
@@ -40,7 +31,7 @@ func newCmdAuthStatus(
 			if runF != nil {
 				return runF(opts)
 			}
-			return authStatusRun(opts, projector)
+			return authStatusRun(opts)
 		},
 	}
 
@@ -51,8 +42,12 @@ func newCmdAuthStatus(
 	return cmd
 }
 
-func authStatusRun(opts *StatusOptions, projector *recovery.Projector) error {
+func authStatusRun(opts *StatusOptions) error {
 	f := opts.Factory
+	editionStatus, err := inspectEditionStatus(f)
+	if err != nil {
+		return err
+	}
 
 	config, err := f.Config()
 	if err != nil {
@@ -69,14 +64,13 @@ func authStatusRun(opts *StatusOptions, projector *recovery.Projector) error {
 		"defaultAs": defaultAs,
 	}
 
-	diagnostics := identitydiag.FilterRecovery(
-		identitydiag.Diagnose(context.Background(), f, config, opts.Verify),
-		projector.CanReference,
-	)
+	diagnostics := identitydiag.Diagnose(context.Background(), f, config, opts.Verify)
 	result["identities"] = diagnostics
 	result["identity"] = effectiveIdentity(diagnostics)
 	addEffectiveVerification(result, diagnostics)
-	addStatusNote(result, diagnostics, projector.CanReference(recovery.TargetAuthLogin))
+	if !applyEditionStatus(result, diagnostics, editionStatus) {
+		addStatusNote(result, diagnostics)
+	}
 
 	output.PrintJson(f.IOStreams.Out, result)
 	return nil
@@ -118,21 +112,13 @@ func addEffectiveVerification(result map[string]interface{}, d identitydiag.Resu
 	}
 }
 
-func addStatusNote(result map[string]interface{}, d identitydiag.Result, canAuthLogin bool) {
+func addStatusNote(result map[string]interface{}, d identitydiag.Result) {
 	switch {
 	case !d.User.Available && d.Bot.Available:
-		note := "User identity is " + identitydiag.StatusMessage(d.User.Status) + "; bot identity is ready for bot/tenant API calls."
-		if canAuthLogin {
-			note += " Run `lark-cli auth login` to enable user identity."
-		}
-		result["note"] = note
+		result["note"] = "User identity is " + identitydiag.StatusMessage(d.User.Status) + "; bot identity is ready for bot/tenant API calls. Run `lark-cli auth login` to enable user identity."
 	case d.User.Status == identitydiag.StatusNeedsRefresh:
 		result["note"] = "User identity needs refresh and will be refreshed automatically on the next user API call."
 	case !d.User.Available && !d.Bot.Available:
-		note := "No usable identity is available. Configure bot credentials"
-		if canAuthLogin {
-			note += " or run `lark-cli auth login`"
-		}
-		result["note"] = note + "."
+		result["note"] = "No usable identity is available. Configure bot credentials or run `lark-cli auth login`."
 	}
 }

cmd/auth/status_edition_extended.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package auth
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/identitydiag"
+)
+
+type editionStatusState struct {
+	provider string
+	variant  string
+}
+
+func inspectEditionStatus(f *cmdutil.Factory) (editionStatusState, error) {
+	if f == nil || f.Credential == nil {
+		return editionStatusState{}, nil
+	}
+	source, err := f.Credential.InspectSource(context.Background())
+	if err != nil {
+		return editionStatusState{}, err
+	}
+	if source == nil || !source.Managed {
+		return editionStatusState{}, nil
+	}
+	state := editionStatusState{provider: source.Name}
+	description := f.RuntimeDescription()
+	if description.Managed {
+		state.variant = description.Variant
+	}
+	return state, nil
+}
+
+func applyEditionStatus(result map[string]interface{}, diagnostics identitydiag.Result, state editionStatusState) bool {
+	if state.provider == "" {
+		return false
+	}
+	result["source"] = "external"
+	result["credentialProvider"] = state.provider
+	if state.variant != "" {
+		result["externalCredentialMode"] = state.variant
+	}
+	switch {
+	case !diagnostics.User.Available && diagnostics.Bot.Available:
+		result["note"] = "User identity is " + identitydiag.StatusMessage(diagnostics.User.Status) +
+			"; bot identity is ready. Update authorization through external credential provider " + state.provider + "."
+	case diagnostics.User.Status == identitydiag.StatusNeedsRefresh:
+		result["note"] = "User identity needs refresh. Check external credential provider " + state.provider + "."
+	case !diagnostics.User.Available && !diagnostics.Bot.Available:
+		result["note"] = "No usable identity is available. Check external credential provider " + state.provider + "."
+	}
+	return true
+}

cmd/auth/status_edition_extended_test.go

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package auth
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/runtimeplan"
+)
+
+func TestExtendedAuthStatusReportsManagedSource(t *testing.T) {
+	cfg := &core.CliConfig{
+		AppID: "cli_env", Brand: core.BrandFeishu, DefaultAs: core.AsBot,
+		SupportedIdentities: uint8(extcred.SupportsBot),
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, cfg)
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{&stubExternalProvider{name: "env"}},
+		nil, nil, f.HttpClient,
+	)
+	cmdutil.TestSetRuntimePlan(t, f, runtimeplan.New(runtimeplan.Options{
+		Description: runtimeplan.Description{
+			Managed: true,
+			Variant: "managed-test",
+		},
+	}))
+
+	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got["source"] != "external" ||
+		got["credentialProvider"] != "env" ||
+		got["externalCredentialMode"] != "managed-test" ||
+		got["identity"] != "bot" {
+		t.Fatalf("output = %#v", got)
+	}
+	if note, _ := got["note"].(string); strings.Contains(note, "auth login") ||
+		!strings.Contains(note, "external credential provider env") {
+		t.Fatalf("note = %q", note)
+	}
+}

cmd/auth/status_edition_standard.go

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package auth
+
+import (
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/identitydiag"
+)
+
+type editionStatusState struct{}
+
+func inspectEditionStatus(*cmdutil.Factory) (editionStatusState, error) {
+	return editionStatusState{}, nil
+}
+
+func applyEditionStatus(map[string]interface{}, identitydiag.Result, editionStatusState) bool {
+	return false
+}

cmd/auth/status_edition_standard_test.go

@@ -0,0 +1,49 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package auth
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+)
+
+func TestStandardAuthStatusPreservesExistingProjection(t *testing.T) {
+	cfg := &core.CliConfig{
+		AppID: "cli_env", Brand: core.BrandFeishu, DefaultAs: core.AsBot,
+		SupportedIdentities: uint8(extcred.SupportsBot),
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, cfg)
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{&stubExternalProvider{name: "env"}},
+		nil, nil, f.HttpClient,
+	)
+
+	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
+		t.Fatal(err)
+	}
+	var got map[string]json.RawMessage
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	for _, field := range []string{"source", "credentialProvider", "externalCredentialMode"} {
+		if _, exists := got[field]; exists {
+			t.Fatalf("Standard auth status contains edition field %q: %s", field, stdout.String())
+		}
+	}
+	var note string
+	if err := json.Unmarshal(got["note"], &note); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(note, "lark-cli auth login") {
+		t.Fatalf("Standard note = %q, want established login guidance", note)
+	}
+}

cmd/auth/status_test.go

@@ -18,7 +18,7 @@ func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
 		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
 	})
 
-	if err := authStatusRun(&StatusOptions{Factory: f}, nil); err != nil {
+	if err := authStatusRun(&StatusOptions{Factory: f}); err != nil {
 		t.Fatalf("authStatusRun() error = %v", err)
 	}
 
@@ -35,6 +35,15 @@ func TestAuthStatusRun_SplitsBotAndUserIdentity(t *testing.T) {
 	if got.Identities.User.Status != "missing" || got.Identities.User.Available {
 		t.Fatalf("user = %#v, want missing and unavailable", got.Identities.User)
 	}
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(stdout.Bytes(), &raw); err != nil {
+		t.Fatalf("json.Unmarshal(raw) error = %v", err)
+	}
+	for _, field := range []string{"source", "credentialProvider", "externalCredentialMode"} {
+		if _, exists := raw[field]; exists {
+			t.Fatalf("local auth status unexpectedly contains edition field %q: %s", field, stdout.String())
+		}
+	}
 }
 
 func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {
@@ -54,7 +63,7 @@ func TestAuthStatusRun_VerifyReportsBotIdentity(t *testing.T) {
 		},
 	})
 
-	if err := authStatusRun(&StatusOptions{Factory: f, Verify: true}, nil); err != nil {
+	if err := authStatusRun(&StatusOptions{Factory: f, Verify: true}); err != nil {
 		t.Fatalf("authStatusRun() error = %v", err)
 	}
 

cmd/bootstrap_test.go

@@ -3,10 +3,7 @@
 
 package cmd
 
-import (
-	"errors"
-	"testing"
-)
+import "testing"
 
 func TestBootstrapInvocationContext_ProfileFlag(t *testing.T) {
 	inv, err := BootstrapInvocationContext([]string{"--profile", "target", "auth", "status"})
@@ -73,18 +70,3 @@ func TestBootstrapInvocationContext_HelpWithProfile(t *testing.T) {
 		t.Fatalf("profile = %q, want %q", inv.Profile, "target")
 	}
 }
-
-func TestIsDeferredBootstrapProfileError(t *testing.T) {
-	if !isDeferredBootstrapProfileError(errors.New("flag needs an argument: --profile")) {
-		t.Fatal("missing --profile value must be deferred to the completed Cobra tree")
-	}
-	for _, err := range []error{
-		nil,
-		errors.New("flag needs an argument: --future"),
-		errors.New("invalid argument for --profile"),
-	} {
-		if isDeferredBootstrapProfileError(err) {
-			t.Fatalf("unexpected deferred bootstrap error: %v", err)
-		}
-	}
-}

cmd/build.go

@@ -21,7 +21,6 @@ import (
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	"github.com/larksuite/cli/cmd/whoami"
 	_ "github.com/larksuite/cli/events"
-	"github.com/larksuite/cli/internal/affordance"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdpolicy"
@@ -29,12 +28,8 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
-	internalplatform "github.com/larksuite/cli/internal/platform"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/internal/skillpolicy"
-	"github.com/larksuite/cli/internal/skillref"
-	"github.com/larksuite/cli/internal/surface"
+	"github.com/larksuite/cli/internal/runtimebootstrap"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
 )
@@ -43,29 +38,15 @@ import (
 type BuildOption func(*buildConfig)
 
 type buildConfig struct {
-	streams         *cmdutil.IOStreams
-	keychain        keychain.KeychainAccess
-	globals         GlobalOptions
-	presentation    restrictionPresentationConfig
-	skipPlugins     bool
-	skipStrictMode  bool
-	skipService     bool
-	deferStartup    bool
-	serviceCatalog  *apicatalog.Catalog
-	startupBrand    core.LarkBrand
-	startupBrandSet bool
-	hideProfileSet  bool
-}
-
-// buildRuntime owns presentation state for exactly one command tree. Factory
-// remains the business dependency container; distribution policy never enters
-// it. The embedded pointer preserves convenient access to Factory fields in
-// cmd-internal tests without exposing the surface plan to business packages.
-type buildRuntime struct {
-	*cmdutil.Factory
-	surface         *surface.Plan
-	recovery        *recovery.Projector
-	skillReferences *skillref.Resolver
+	streams        *cmdutil.IOStreams
+	keychain       keychain.KeychainAccess
+	globals        GlobalOptions
+	skipPlugins    bool
+	skipStrictMode bool
+	skipService    bool
+	serviceCatalog *apicatalog.Catalog
+	startupBrand   core.LarkBrand
+	runtime        *runtimebootstrap.Result
 }
 
 // WithStartupBrand initializes the API registry with the given brand before
@@ -76,7 +57,14 @@ type buildRuntime struct {
 func WithStartupBrand(brand core.LarkBrand) BuildOption {
 	return func(c *buildConfig) {
 		c.startupBrand = brand
-		c.startupBrandSet = true
+	}
+}
+
+// withRuntimeBootstrap shares one invocation snapshot across registry,
+// credentials, transports, and command capabilities.
+func withRuntimeBootstrap(runtime *runtimebootstrap.Result) BuildOption {
+	return func(c *buildConfig) {
+		c.runtime = runtime
 	}
 }
 
@@ -107,12 +95,6 @@ var embeddedSkillContent fs.FS
 // supply its own skill content.
 func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
 
-// SetEmbeddedAffordanceContent registers the per-domain command guidance tree.
-// Wrapper mains should wire the repository's affordance directory alongside
-// embedded skills so generic --help presentation remains complete and skill
-// references follow the composed distribution.
-func SetEmbeddedAffordanceContent(fsys fs.FS) { affordance.SetSource(fsys) }
-
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -120,7 +102,6 @@ func SetEmbeddedAffordanceContent(fsys fs.FS) { affordance.SetSource(fsys) }
 func HideProfile(hide bool) BuildOption {
 	return func(c *buildConfig) {
 		c.globals.HideProfile = hide
-		c.hideProfileSet = true
 	}
 }
 
@@ -172,15 +153,15 @@ func Build(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOpti
 	return rootCmd
 }
 
-// buildInternal is a pure assembly function: it wires the command tree from
-// inv and BuildOptions alone. Any state-dependent decision (disk, network,
-// env) belongs in the caller and must be threaded in via BuildOption.
+// buildInternal assembles the command tree from one immutable startup
+// configuration snapshot. Profile selection happens before any registry
+// network decision and the same result is passed to the Factory.
 //
-// Returns (runtime, rootCmd, registry). The registry is nil when plugin
+// Returns (factory, rootCmd, registry). The registry is nil when plugin
 // install failed (FailClosed guard installed) or when no plugin produced
 // hooks; callers that wire Shutdown emit must nil-check before calling
 // hook.Emit.
-func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*buildRuntime, *cobra.Command, *hook.Registry) {
+func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command, *hook.Registry) {
 	// cfg.globals.Profile is left zero here; it's bound to the --profile
 	// flag in RegisterGlobalFlags and filled by cobra's parse step.
 	cfg := &buildConfig{}
@@ -189,16 +170,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 			o(cfg)
 		}
 	}
-	return buildInternalWithConfig(ctx, inv, cfg)
-}
-
-// buildInternalWithConfig assembles one command tree from an already-applied
-// option snapshot. Execute uses this boundary so stateful BuildOptions are
-// never evaluated once for bootstrap inspection and a second time for Build.
-func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext, cfg *buildConfig) (*buildRuntime, *cobra.Command, *hook.Registry) {
-	if cfg == nil {
-		cfg = &buildConfig{}
-	}
 	// Default streams when WithIO is not supplied so the root command's
 	// SetIn/Out/Err calls below don't deref nil. NewDefault also normalizes
 	// partial streams internally; keep both in sync so cfg.streams reflects
@@ -206,28 +177,34 @@ func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext,
 	if cfg.streams == nil {
 		cfg.streams = cmdutil.SystemIO()
 	}
-	// Initialize the registry brand before anything touches the runtime
-	// catalog (its sync.Once would otherwise lock onto the Feishu default).
-	if cfg.startupBrand != "" {
-		registry.InitWithBrand(cfg.startupBrand)
+
+	startup := cfg.runtime
+	if startup == nil {
+		startup = runtimebootstrap.Resolve(inv.Profile)
 	}
 
-	// Reset the legacy process-global diagnostic snapshots before paths that
-	// may return early. Distribution presentation state is deliberately not
-	// stored here; it belongs to this build's immutable surface plan.
-	cmdpolicy.SetActive(nil)
-	internalplatform.SetActiveInventory(nil)
+	// Initialize the registry brand before anything touches the runtime
+	// catalog (its sync.Once would otherwise lock onto the Feishu default).
+	// Runtime policy can close direct metadata egress before any command is
+	// registered, without exposing a concrete credential mode here.
+	registryBrand := cfg.startupBrand
+	if registryBrand == "" {
+		registryBrand = resolveStartupBrandFromConfig(inv.Profile, startup.ProfileConfig)
+	}
+	if !startup.Plan.AllowsRemoteMetadata() {
+		if registryBrand == "" {
+			registryBrand = core.BrandFeishu
+		}
+		registry.InitEmbeddedWithBrand(registryBrand)
+	} else if registryBrand != "" {
+		registry.InitWithBrand(registryBrand)
+	}
 
-	f := cmdutil.NewDefault(cfg.streams, inv)
+	f := cmdutil.NewDefaultWithRuntimePlan(cfg.streams, inv, startup.ProfileConfig, startup.Plan)
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
 	f.SkillContent = embeddedSkillContent
-	runtime := &buildRuntime{Factory: f}
-	runtime.recovery = recovery.NewProjector(func() *surface.Plan {
-		return runtime.surface
-	})
-	f.Recovery = runtime.recovery
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -244,17 +221,7 @@ func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext,
 	// rootUsageTemplate.
 	rootCmd.SetUsageTemplate(rootUsageTemplate)
 
-	// Framework-generated skill pointers read this build's final content and
-	// exact command surface lazily. A second Build therefore cannot rewrite
-	// help rendered by the first tree.
-	installTipsHelpFunc(rootCmd, func() fs.FS {
-		if !runtime.surface.CanReference(surface.CommandSkillsRead) {
-			return nil
-		}
-		return runtime.SkillContent
-	}, func() *skillref.Resolver {
-		return runtime.skillReferences
-	}, runtime.recovery)
+	installTipsHelpFunc(rootCmd)
 	rootCmd.SilenceErrors = true
 	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
 	// covers flag-parse errors, which fail before PreRun runs — otherwise cobra
@@ -270,15 +237,16 @@ func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext,
 		f.CurrentCommand = cmd
 	}
 
-	rootCmd.AddCommand(cmdconfig.NewCmdConfigWithRecovery(f, runtime.recovery))
-	rootCmd.AddCommand(auth.NewCmdAuthWithRecovery(f, runtime.recovery))
+	rootCmd.AddCommand(cmdconfig.NewCmdConfig(f))
+	rootCmd.AddCommand(auth.NewCmdAuth(f))
 	rootCmd.AddCommand(profile.NewCmdProfile(f))
-	rootCmd.AddCommand(doctor.NewCmdDoctorWithRecovery(f, runtime.recovery))
-	rootCmd.AddCommand(whoami.NewCmdWhoamiWithRecovery(f, runtime.recovery))
+	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
+	rootCmd.AddCommand(whoami.NewCmdWhoami(f))
 	rootCmd.AddCommand(api.NewCmdApiWithContext(ctx, f, nil))
 	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
+	registerEditionCommands(rootCmd, f)
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
 	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	if !cfg.skipService {
@@ -290,93 +258,52 @@ func buildInternalWithConfig(ctx context.Context, inv cmdutil.InvocationContext,
 	}
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 
-	classifyRootCommands(rootCmd)
+	groupRootCommands(rootCmd)
 
 	installUnknownSubcommandGuard(rootCmd)
 	// Bare `lark-cli` in an interactive terminal offers an interactive upgrade
 	// before printing help; non-bare invocations and non-TTY are unaffected.
-	installRootUpgradePrompt(f, rootCmd, runtime.recovery)
+	installRootUpgradePrompt(f, rootCmd)
 
 	if mode := f.ResolveStrictMode(ctx); mode.IsActive() && !cfg.skipStrictMode {
 		pruneForStrictMode(rootCmd, mode)
 	}
 
-	var (
-		installResult *internalplatform.InstallResult
-		pluginRules   []cmdpolicy.PluginRule
-		pluginSkills  []skillpolicy.PluginSkill
-		hookRegistry  *hook.Registry
-		denied        map[string]cmdpolicy.Denial
-	)
+	if cfg.skipPlugins {
+		recordInventory(nil)
+		return f, rootCmd, nil
+	}
 
-	if !cfg.skipPlugins {
-		var installErr error
-		installResult, installErr = installPluginsAndHooks(cfg.streams.ErrOut)
-		if installErr != nil {
-			installPluginInstallErrorGuard(rootCmd, installErr)
-			return finalizeFailedBuild(runtime, rootCmd)
-		}
-		if installResult != nil {
-			pluginRules = installResult.PluginRules
-			pluginSkills = installResult.PluginSkills
-			hookRegistry = installResult.Registry
-		}
-
-		// Policy errors fail-CLOSED when a plugin contributed (security
-		// intent must not be silently dropped); yaml-only errors fail-OPEN
-		// with a warning so a typo can't lock the user out.
-		var policyErr error
-		denied, policyErr = applyUserPolicyPruning(rootCmd, pluginRules)
-		if policyErr != nil {
-			if len(pluginRules) > 0 {
-				installPluginConflictGuard(rootCmd, policyErr)
-				return finalizeFailedBuild(runtime, rootCmd)
-			}
-			warnPolicyError(cfg.streams.ErrOut, policyErr)
+	installResult, installErr := installPluginsAndHooks(cfg.streams.ErrOut)
+	if installErr != nil {
+		installPluginInstallErrorGuard(rootCmd, installErr)
+		return f, rootCmd, nil
+	}
+	var pluginRules []cmdpolicy.PluginRule
+	var registry *hook.Registry
+	if installResult != nil {
+		pluginRules = installResult.PluginRules
+		registry = installResult.Registry
+	}
+
+	// Policy errors fail-CLOSED when a plugin contributed (security
+	// intent must not be silently dropped); yaml-only errors fail-OPEN
+	// with a warning so a typo can't lock the user out.
+	if err := applyUserPolicyPruning(rootCmd, pluginRules); err != nil {
+		if len(pluginRules) > 0 {
+			installPluginConflictGuard(rootCmd, err)
+			return f, rootCmd, nil
 		}
+		warnPolicyError(cfg.streams.ErrOut, err)
 	}
 
-	// Presentation is an explicit host projection over the exact enforcement
-	// decisions. With no opt-in, legacy Restrict and YAML policy behavior is
-	// mechanically unchanged.
-	var hasConcealedCommands bool
-	runtime.surface, hasConcealedCommands = applyDistributionPresentation(rootCmd, cfg.presentation, denied)
-
-	// Resolve skill assets and canonical references before installing hooks.
-	// A declared customization is a build-integrity boundary: failure must
-	// happen before Startup so no lifecycle side effect is stranded.
-	skillResolution, skillErr := skillpolicy.ResolveWithReferences(embeddedSkillContent, pluginSkills)
-	if skillErr != nil {
-		installPluginSkillErrorGuard(rootCmd, skillErr)
-		return finalizeFailedBuild(runtime, rootCmd)
-	}
-	f.SkillContent = skillResolution.Content
-	runtime.skillReferences = skillResolution.References
-
-	// Install hooks only on business commands. The concealment-specific help
-	// command is attached afterwards, preserving Cobra's historical contract
-	// that help is not observed or wrapped by plugins.
-	if hookRegistry != nil {
-		installHooks(rootCmd, hookRegistry)
-	}
-	if hasConcealedCommands {
-		installHelpCommand(rootCmd)
-	}
-	finalizeRootCommandGroups(rootCmd, runtime.surface)
-
-	if hookRegistry != nil && !cfg.deferStartup {
-		if err := emitStartup(ctx, hookRegistry); err != nil {
+	if registry != nil {
+		if err := wireHooks(ctx, rootCmd, registry); err != nil {
 			installPluginLifecycleErrorGuard(rootCmd, err)
-			recordInventory(installResult)
-			return runtime, rootCmd, nil
+			return f, rootCmd, nil
 		}
 	}
 
 	recordInventory(installResult)
-	return runtime, rootCmd, hookRegistry
-}
-
-func finalizeFailedBuild(runtime *buildRuntime, root *cobra.Command) (*buildRuntime, *cobra.Command, *hook.Registry) {
-	finalizeRootCommandGroups(root, runtime.surface)
-	return runtime, root, nil
+	return f, rootCmd, registry
 }

cmd/build_api_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"testing"
-	"testing/fstest"
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/vfs"
@@ -29,10 +28,6 @@ func TestBuild_ExternalAPI(t *testing.T) {
 	// Exercise SetDefaultFS both directions. Passing nil restores the OS FS.
 	SetDefaultFS(vfs.OsFs{})
 	SetDefaultFS(nil)
-	SetEmbeddedAffordanceContent(fstest.MapFS{
-		"docs.md": {Data: []byte("# docs\n")},
-	})
-	t.Cleanup(func() { SetEmbeddedAffordanceContent(nil) })
 
 	var in, out, errOut bytes.Buffer
 	rootCmd := Build(

cmd/build_workspace_test.go

@@ -0,0 +1,176 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"io"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/envvars"
+)
+
+func TestStartupProfileSnapshotUsesDetectedWorkspace(t *testing.T) {
+	previousWorkspace := core.CurrentWorkspace()
+	t.Cleanup(func() { core.SetCurrentWorkspace(previousWorkspace) })
+
+	tests := []struct {
+		name          string
+		workspace     core.Workspace
+		signalName    string
+		signalValue   string
+		expectedAppID string
+		expectedBrand core.LarkBrand
+	}{
+		{
+			name:          "local",
+			workspace:     core.WorkspaceLocal,
+			expectedAppID: "cli_local",
+			expectedBrand: core.BrandFeishu,
+		},
+		{
+			name:          "openclaw",
+			workspace:     core.WorkspaceOpenClaw,
+			signalName:    "OPENCLAW_CLI",
+			signalValue:   "1",
+			expectedAppID: "cli_openclaw",
+			expectedBrand: core.BrandLark,
+		},
+		{
+			name:          "hermes",
+			workspace:     core.WorkspaceHermes,
+			signalName:    "HERMES_HOME",
+			signalValue:   "/managed/hermes",
+			expectedAppID: "cli_hermes",
+			expectedBrand: core.BrandLark,
+		},
+		{
+			name:          "lark_channel",
+			workspace:     core.WorkspaceLarkChannel,
+			signalName:    "LARK_CHANNEL",
+			signalValue:   "1",
+			expectedAppID: "cli_lark_channel",
+			expectedBrand: core.BrandLark,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clearWorkspaceSignals(t)
+			clearCredentialSignals(t)
+			configRoot := t.TempDir()
+			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configRoot)
+			t.Setenv(envvars.CliExternalCredentialConfig,
+				filepath.Join(configRoot, "missing-external-credential.json"))
+			t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+			if tt.signalName != "" {
+				t.Setenv(tt.signalName, tt.signalValue)
+			}
+
+			writeWorkspaceProfile(t, core.WorkspaceLocal, "local", "cli_local", core.BrandFeishu)
+			if !tt.workspace.IsLocal() {
+				writeWorkspaceProfile(t, tt.workspace, tt.name, tt.expectedAppID, tt.expectedBrand)
+			}
+
+			// Execute resolves the registry brand before entering
+			// buildInternal. Pin that ordering independently.
+			core.SetCurrentWorkspace(core.WorkspaceLocal)
+			if got := selectInvocationWorkspace(); got != tt.workspace {
+				t.Fatalf("selected workspace = %q, want %q", got, tt.workspace)
+			}
+			if got := ResolveStartupBrand(""); got != tt.expectedBrand {
+				t.Fatalf("startup brand = %q, want %q", got, tt.expectedBrand)
+			}
+
+			// Build/buildInternal is also a public construction path. Reset the
+			// process state to local so the test proves it establishes the
+			// workspace before SelectProfile captures the immutable snapshot.
+			core.SetCurrentWorkspace(core.WorkspaceLocal)
+			factory, _, _ := buildInternal(
+				context.Background(),
+				cmdutil.InvocationContext{},
+				WithIO(strings.NewReader(""), io.Discard, io.Discard),
+				WithoutPlugins(),
+				WithoutServiceCommands(),
+			)
+			if got := core.CurrentWorkspace(); got != tt.workspace {
+				t.Fatalf("workspace after build = %q, want %q", got, tt.workspace)
+			}
+			config, err := factory.Config()
+			if err != nil {
+				t.Fatalf("Factory.Config() error = %v", err)
+			}
+			if config.AppID != tt.expectedAppID || config.Brand != tt.expectedBrand {
+				t.Fatalf("resolved config = app %q (%s), want app %q (%s)",
+					config.AppID, config.Brand, tt.expectedAppID, tt.expectedBrand)
+			}
+		})
+	}
+}
+
+func clearWorkspaceSignals(t *testing.T) {
+	t.Helper()
+	for _, name := range []string{
+		"OPENCLAW_CLI",
+		"OPENCLAW_HOME",
+		"OPENCLAW_STATE_DIR",
+		"OPENCLAW_CONFIG_PATH",
+		"OPENCLAW_SERVICE_MARKER",
+		"OPENCLAW_SERVICE_VERSION",
+		"OPENCLAW_GATEWAY_PORT",
+		"OPENCLAW_SHELL",
+		"HERMES_HOME",
+		"HERMES_QUIET",
+		"HERMES_EXEC_ASK",
+		"HERMES_GATEWAY_TOKEN",
+		"HERMES_SESSION_KEY",
+		"LARK_CHANNEL",
+	} {
+		t.Setenv(name, "")
+	}
+}
+
+func clearCredentialSignals(t *testing.T) {
+	t.Helper()
+	for _, name := range []string{
+		envvars.CliAppID,
+		envvars.CliAppSecret,
+		envvars.CliBrand,
+		envvars.CliUserAccessToken,
+		envvars.CliTenantAccessToken,
+		envvars.CliDefaultAs,
+		envvars.CliStrictMode,
+	} {
+		t.Setenv(name, "")
+	}
+}
+
+func writeWorkspaceProfile(
+	t *testing.T,
+	workspace core.Workspace,
+	name string,
+	appID string,
+	brand core.LarkBrand,
+) {
+	t.Helper()
+	previous := core.CurrentWorkspace()
+	core.SetCurrentWorkspace(workspace)
+	defer core.SetCurrentWorkspace(previous)
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
+		CurrentApp: name,
+		Apps: []core.AppConfig{{
+			Name:      name,
+			AppId:     appID,
+			AppSecret: core.PlainSecret("test-secret-" + name),
+			Brand:     brand,
+			Users:     []core.AppUser{},
+		}},
+	}); err != nil {
+		t.Fatalf("save %s workspace profile: %v", workspace.Display(), err)
+	}
+}

cmd/config/bind.go

@@ -18,7 +18,6 @@ import (
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -60,14 +59,6 @@ type BindOptions struct {
 
 // NewCmdConfigBind creates the config bind subcommand.
 func NewCmdConfigBind(f *cmdutil.Factory, runF func(*BindOptions) error) *cobra.Command {
-	return newCmdConfigBind(f, runF, nil)
-}
-
-func newCmdConfigBind(
-	f *cmdutil.Factory,
-	runF func(*BindOptions) error,
-	projector *recovery.Projector,
-) *cobra.Command {
 	opts := &BindOptions{Factory: f, UILang: i18n.LangZhCN}
 
 	cmd := &cobra.Command{
@@ -107,7 +98,7 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 			if runF != nil {
 				return runF(opts)
 			}
-			return configBindRunWithRecovery(opts, projector)
+			return configBindRun(opts)
 		},
 	}
 
@@ -125,10 +116,6 @@ Interactive terminal use: run with no flags to enter the TUI form.`,
 // helper whose signature declares its contract; the body reads as the shape of
 // the bind flow itself, not its mechanics.
 func configBindRun(opts *BindOptions) error {
-	return configBindRunWithRecovery(opts, nil)
-}
-
-func configBindRunWithRecovery(opts *BindOptions, projector *recovery.Projector) error {
 	if err := validateBindFlags(opts); err != nil {
 		return err
 	}
@@ -167,7 +154,7 @@ func configBindRunWithRecovery(opts *BindOptions, projector *recovery.Projector)
 	applyPreferences(appConfig, opts, priorLang(existing.ConfigBytes))
 	noticeUserDefaultRisk(opts)
 
-	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath, projector)
+	return commitBinding(opts, appConfig, existing.ConfigBytes, source, targetConfigPath)
 }
 
 // existingBinding is the outcome of checking whether a workspace was already
@@ -417,13 +404,7 @@ func priorLang(previousConfigBytes []byte) i18n.Lang {
 // any), and a JSON success envelope. Cleanup runs only after the new config
 // is durably written — if anything fails earlier, the old workspace stays
 // usable.
-func commitBinding(
-	opts *BindOptions,
-	appConfig *core.AppConfig,
-	previousConfigBytes []byte,
-	source, configPath string,
-	projector *recovery.Projector,
-) error {
+func commitBinding(opts *BindOptions, appConfig *core.AppConfig, previousConfigBytes []byte, source, configPath string) error {
 	multi := &core.MultiAppConfig{Apps: []core.AppConfig{*appConfig}}
 
 	if err := vfs.MkdirAll(core.GetConfigDir(), 0700); err != nil {
@@ -481,7 +462,7 @@ func commitBinding(
 	case "bot-only":
 		envelope["message"] = fmt.Sprintf(prefMsg.MessageBotOnly, appConfig.AppId, display, brand)
 	case "user-default":
-		envelope["message"] = userDefaultBindMessage(prefMsg, appConfig.AppId, display, projector)
+		envelope["message"] = fmt.Sprintf(prefMsg.MessageUserDefault, appConfig.AppId, display, display)
 	}
 
 	resultJSON, _ := json.Marshal(envelope)
@@ -489,17 +470,6 @@ func commitBinding(
 	return nil
 }
 
-func userDefaultBindMessage(
-	messages *bindMsg,
-	appID, display string,
-	projector *recovery.Projector,
-) string {
-	if projector.CanReference(recovery.TargetAuthLogin) {
-		return fmt.Sprintf(messages.MessageUserDefault, appID, display, display)
-	}
-	return fmt.Sprintf(messages.MessageUserDefaultFallback, appID, display)
-}
-
 // cleanupKeychainFromData removes keychain entries referenced by a previous
 // config snapshot, skipping any entry whose keychain ID is still in use by
 // the new app config. This prevents rebinding the same appId from deleting

cmd/config/bind_messages.go

@@ -37,9 +37,6 @@ type bindMsg struct {
 	// MessageBotOnly format: app_id, source display name, brand.
 	// MessageUserDefault format: app_id, source display name, source display
 	// name (second source ref anchors the "run in this chat" directive).
-	// MessageUserDefaultFallback format: app_id, source display name. It keeps
-	// the completed bind facts but uses target-free recovery when auth/login
-	// is not part of this distribution.
 	// MessageUserDefault directs the Agent at the blocking single-call
 	// `auth login --recommend` flow: the CLI streams verification_url to
 	// stderr, which Agent runtimes (OpenClaw, Hermes) relay to the user in
@@ -47,9 +44,8 @@ type bindMsg struct {
 	// The Agent also needs an explicit "do not navigate the URL yourself"
 	// guard — its own browser is sandboxed and cannot complete the user's
 	// authorization.
-	MessageBotOnly             string
-	MessageUserDefault         string
-	MessageUserDefaultFallback string
+	MessageBotOnly     string
+	MessageUserDefault string
 
 	// Identity preset (collapses strict-mode + default-as into one choice).
 	// IdentityBotOnly/IdentityUserDefault are short, single-line labels for
@@ -112,9 +108,8 @@ var bindMsgZh = &bindMsg{
 	ConflictCancel:    "保留当前配置",
 	ConflictCancelled: "已保留当前配置",
 
-	MessageBotOnly:             "已绑定应用 %s 到 %s，可立即以应用（bot）身份调用%s API，现在可以继续执行用户的请求。",
-	MessageUserDefault:         "已绑定应用 %s 到 %s。请接着在此 %s 对话中运行 `lark-cli auth login --recommend`。该命令会在 stderr 打出 verification_url 后阻塞等待用户授权；请将此链接原样发给用户在其浏览器中完成授权（不要自己调 browser_navigate 之类的工具打开，授权必须在用户的浏览器里完成），命令会在用户授权完成后自动返回。",
-	MessageUserDefaultFallback: "已绑定应用 %s 到 %s。请通过该发行版支持的授权流程获取或刷新用户凭证，然后再继续执行用户的请求。",
+	MessageBotOnly:     "已绑定应用 %s 到 %s，可立即以应用（bot）身份调用%s API，现在可以继续执行用户的请求。",
+	MessageUserDefault: "已绑定应用 %s 到 %s。请接着在此 %s 对话中运行 `lark-cli auth login --recommend`。该命令会在 stderr 打出 verification_url 后阻塞等待用户授权；请将此链接原样发给用户在其浏览器中完成授权（不要自己调 browser_navigate 之类的工具打开，授权必须在用户的浏览器里完成），命令会在用户授权完成后自动返回。",
 
 	SelectIdentity:      "你希望 AI 如何与你协作？",
 	IdentityBotOnly:     "以机器人身份",
@@ -149,9 +144,8 @@ var bindMsgEn = &bindMsg{
 	ConflictCancel:    "Keep current config",
 	ConflictCancelled: "Current config kept. No changes made.",
 
-	MessageBotOnly:             "Bound app %s to %s. The %s app (bot) identity is ready — you can now continue with the user's request.",
-	MessageUserDefault:         "Bound app %s to %s. Next, in this %s chat, run `lark-cli auth login --recommend`. The command prints the verification URL to stderr and then blocks until the user authorizes it; relay the URL to the user so they can approve it in their own browser (do not call browser_navigate or any tool that opens a browser yourself — your browser is sandboxed and cannot complete the authorization). The command returns automatically once authorization completes.",
-	MessageUserDefaultFallback: "Bound app %s to %s. Obtain or refresh a user credential through this distribution's supported authorization flow before continuing with the user's request.",
+	MessageBotOnly:     "Bound app %s to %s. The %s app (bot) identity is ready — you can now continue with the user's request.",
+	MessageUserDefault: "Bound app %s to %s. Next, in this %s chat, run `lark-cli auth login --recommend`. The command prints the verification URL to stderr and then blocks until the user authorizes it; relay the URL to the user so they can approve it in their own browser (do not call browser_navigate or any tool that opens a browser yourself — your browser is sandboxed and cannot complete the authorization). The command returns automatically once authorization completes.",
 
 	SelectIdentity:      "How should the AI work with you?",
 	IdentityBotOnly:     "As bot",

cmd/config/bind_warning_test.go

@@ -10,8 +10,6 @@ import (
 	"testing"
 
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 )
 
 // runHermesBindWithIdentity boots a Hermes-shaped fake env, runs `config bind`
@@ -62,29 +60,3 @@ func TestConfigBindRun_BotOnlyIdentity_NoImpersonationWarning(t *testing.T) {
 		t.Errorf("bot-only bind must NOT warn about impersonation; got: %s", out)
 	}
 }
-
-func TestUserDefaultBindMessageProjectsConcealedLogin(t *testing.T) {
-	visible := userDefaultBindMessage(bindMsgEn, "cli_test", "Hermes", nil)
-	if !strings.Contains(visible, "lark-cli auth login --recommend") {
-		t.Fatalf("default message lost established login action: %q", visible)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandAuthLogin: surface.CommandConcealed,
-	})
-	concealed := userDefaultBindMessage(
-		bindMsgEn,
-		"cli_test",
-		"Hermes",
-		recovery.NewProjector(func() *surface.Plan { return plan }),
-	)
-	if strings.Contains(concealed, "auth login") ||
-		!strings.Contains(concealed, "supported authorization flow") {
-		t.Fatalf("concealed message = %q, want target-free authorization fallback", concealed)
-	}
-	for _, want := range []string{"cli_test", "Hermes"} {
-		if !strings.Contains(concealed, want) {
-			t.Errorf("concealed message lost binding fact %q: %q", want, concealed)
-		}
-	}
-}

cmd/config/config.go

@@ -6,22 +6,12 @@ package config
 import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/recovery"
+	"github.com/larksuite/cli/internal/runtimeplan"
 	"github.com/spf13/cobra"
 )
 
 // NewCmdConfig creates the config command with subcommands.
 func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
-	return newCmdConfig(f, nil)
-}
-
-// NewCmdConfigWithRecovery creates the config command with build-local
-// recovery projection while preserving NewCmdConfig's established signature.
-func NewCmdConfigWithRecovery(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
-	return newCmdConfig(f, projector)
-}
-
-func newCmdConfig(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
 		Short: "Global CLI configuration management",
@@ -30,22 +20,38 @@ func newCmdConfig(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Comm
 			// PersistentPreRun[E] found walking up the chain, so the root-level
 			// SilenceUsage=true would be skipped without this line.
 			cmd.SilenceUsage = true
-			// Pass "config" as a literal — cmd.Name() would return the subcommand name.
-			return f.RequireBuiltinCredentialProvider(cmd.Context(), "config")
+			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalCredentialManagement)
 
-	cmd.AddCommand(NewCmdConfigInit(f, nil))
-	cmd.AddCommand(newCmdConfigBind(f, nil, projector))
-	cmd.AddCommand(NewCmdConfigRemove(f, nil))
-	cmd.AddCommand(NewCmdConfigShow(f, nil))
-	cmd.AddCommand(NewCmdConfigDefaultAs(f))
-	cmd.AddCommand(NewCmdConfigStrictMode(f))
-	cmd.AddCommand(NewCmdConfigRiskControl(f))
-	cmd.AddCommand(NewCmdConfigPolicy(f))
-	cmd.AddCommand(NewCmdConfigPlugins(f))
-	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))
+	initCmd := NewCmdConfigInit(f, nil)
+	bind := NewCmdConfigBind(f, nil)
+	remove := NewCmdConfigRemove(f, nil)
+	show := NewCmdConfigShow(f, nil)
+	defaultAs := NewCmdConfigDefaultAs(f)
+	strictMode := NewCmdConfigStrictMode(f)
+	riskControl := NewCmdConfigRiskControl(f)
+	policy := NewCmdConfigPolicy(f)
+	plugins := NewCmdConfigPlugins(f)
+	keychainDowngrade := NewCmdConfigKeychainDowngrade(f)
+	// Identity preferences live in the Profile, but external providers have
+	// historically treated these config commands as credential management.
+	// Check Profile ownership first so a managed runtime gives the actionable
+	// deployment-managed Profile error, then retain the credential capability
+	// so Standard external-provider behavior stays unchanged.
+	for _, identitySetting := range []*cobra.Command{defaultAs, strictMode} {
+		cmdutil.SetRuntimeCapabilities(
+			identitySetting,
+			runtimeplan.CapabilityLocalProfileMutation,
+			runtimeplan.CapabilityLocalCredentialManagement,
+		)
+	}
+	for _, sourceNeutral := range []*cobra.Command{show, riskControl, policy, plugins} {
+		cmdutil.SetRuntimeCapabilities(sourceNeutral)
+	}
+	cmd.AddCommand(initCmd, bind, remove, show, defaultAs, strictMode, riskControl, policy, plugins, keychainDowngrade)
 	return cmd
 }
 

cmd/config/config_test.go

@@ -20,8 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
+	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 type noopConfigKeychain struct{}
@@ -454,10 +453,16 @@ func TestUpdateExistingProfileWithoutSecret_RejectsAppIDChange(t *testing.T) {
 }
 
 // stubConfigExtProvider simulates env/sidecar credential mode for config guard tests.
-type stubConfigExtProvider struct{ name string }
+type stubConfigExtProvider struct {
+	name string
+	err  error
+}
 
 func (s *stubConfigExtProvider) Name() string { return s.name }
 func (s *stubConfigExtProvider) ResolveAccount(_ context.Context) (*extcred.Account, error) {
+	if s.err != nil {
+		return nil, s.err
+	}
 	return &extcred.Account{AppID: "test-app"}, nil
 }
 func (s *stubConfigExtProvider) ResolveToken(_ context.Context, _ extcred.TokenSpec) (*extcred.Token, error) {
@@ -483,7 +488,6 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 	}{
 		{"init", []string{"init", "--app-id", "x", "--app-secret-stdin"}},
 		{"remove", []string{"remove"}},
-		{"show", []string{"show"}},
 		{"default-as", []string{"default-as", "user"}},
 		{"strict-mode", []string{"strict-mode", "off"}},
 	}
@@ -511,6 +515,63 @@ func TestConfigBlockedByExternalProvider(t *testing.T) {
 	}
 }
 
+func TestConfigIdentityCommandsCheckProfileOwnershipBeforeCredentialOwnership(t *testing.T) {
+	profileDenied := errors.New("Profile identity settings are deployment-managed")
+	credentialChecks := 0
+	plan := runtimeplan.New(runtimeplan.Options{
+		Capabilities: func(capability runtimeplan.Capability) error {
+			switch capability {
+			case runtimeplan.CapabilityLocalProfileMutation:
+				return profileDenied
+			case runtimeplan.CapabilityLocalCredentialManagement:
+				credentialChecks++
+			}
+			return nil
+		},
+	})
+
+	for _, args := range [][]string{
+		{"default-as", "bot"},
+		{"strict-mode", "bot"},
+	} {
+		t.Run(args[0], func(t *testing.T) {
+			f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
+			cmd := NewCmdConfig(f)
+			cmd.SetArgs(args)
+
+			err := cmd.Execute()
+			if !errors.Is(err, profileDenied) {
+				t.Fatalf("Execute(%v) error = %v, want Profile ownership denial", args, err)
+			}
+		})
+	}
+	if credentialChecks != 0 {
+		t.Fatalf("credential capability checked %d times after Profile denial, want 0", credentialChecks)
+	}
+}
+
+func TestConfigIdentityCommandsRetainCredentialOwnershipCapability(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	root := NewCmdConfig(f)
+
+	for _, name := range []string{"default-as", "strict-mode"} {
+		t.Run(name, func(t *testing.T) {
+			leaf, _, err := root.Find([]string{name})
+			if err != nil {
+				t.Fatal(err)
+			}
+			got := cmdutil.GetRuntimeCapabilities(leaf)
+			want := []runtimeplan.Capability{
+				runtimeplan.CapabilityLocalProfileMutation,
+				runtimeplan.CapabilityLocalCredentialManagement,
+			}
+			if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+				t.Fatalf("%s capabilities = %v, want %v", name, got, want)
+			}
+		})
+	}
+}
+
 // TestValidateInitLang covers the --lang contract: empty (omitted or explicit)
 // is a no-op leaving Lang unset; a short code or Feishu locale canonicalizes to
 // the same locale; an unrecognized value errors.
@@ -566,59 +627,3 @@ func TestPrintLangPreferenceConfirmation(t *testing.T) {
 		}
 	})
 }
-
-// The "no active profile" producer annotates its profile/list recovery target.
-// Rendering against one build's surface filters a clone without mutating the
-// value another command tree may render.
-func TestConfigShowRun_ProfileHintUsesBuildLocalSurface(t *testing.T) {
-	multi := &core.MultiAppConfig{
-		CurrentApp: "missing",
-		Apps: []core.AppConfig{{
-			Name:      "default",
-			AppId:     "app-default",
-			AppSecret: core.PlainSecret("secret-default"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	source := configShowRun(&ConfigShowOptions{Factory: f})
-	var original *errs.ConfigError
-	if !errors.As(source, &original) {
-		t.Fatalf("expected *errs.ConfigError, got %T %v", source, source)
-	}
-	if original.Subtype != errs.SubtypeNotConfigured {
-		t.Fatalf("subtype = %q, want not_configured", original.Subtype)
-	}
-	if !strings.Contains(original.Hint, "lark-cli profile list") {
-		t.Fatalf("producer hint = %q, want profile list", original.Hint)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandProfileList: surface.CommandConcealed,
-	})
-	var concealed *errs.ConfigError
-	if rendered := recovery.Render(source, plan); !errors.As(rendered, &concealed) {
-		t.Fatalf("rendered error = %T, want *errs.ConfigError", rendered)
-	}
-	if concealed == original {
-		t.Fatal("Render must clone the typed error")
-	}
-	if strings.Contains(concealed.Hint, "profile list") ||
-		!strings.Contains(concealed.Hint, "select or configure an available profile") {
-		t.Errorf("concealed hint = %q, want target-free profile recovery", concealed.Hint)
-	}
-
-	var visible *errs.ConfigError
-	if !errors.As(recovery.Render(source, nil), &visible) ||
-		!strings.Contains(visible.Hint, "lark-cli profile list") {
-		t.Errorf("visible render must keep profile list, got %+v", visible)
-	}
-	if !strings.Contains(original.Hint, "lark-cli profile list") {
-		t.Errorf("concealed render mutated source hint: %q", original.Hint)
-	}
-}

cmd/config/init.go

@@ -20,7 +20,6 @@ import (
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // ConfigInitOptions holds all inputs for config init.
@@ -41,44 +40,13 @@ type ConfigInitOptions struct {
 	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
 
 	// ForceInit overrides the agent-workspace guard. Without it, running
-	// init under OPENCLAW_HOME / HERMES_HOME refuses so the distribution's
-	// supported Agent-app setup flow remains the default. Manual users with
-	// a legitimate need for a separate app can pass --force-init to bypass.
+	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
+	// at config bind — which is what AI agents almost always want. Manual
+	// users with a legitimate need for a separate app can pass --force-init
+	// to bypass.
 	ForceInit bool
 }
 
-const (
-	configInitLongPrefix = `Initialize configuration (app-id / app-secret-stdin / brand).
-
-For AI agents: use --new to create a new app. The command blocks until the user
-completes setup in the browser. Run it in the background and retrieve the
-verification URL from its output.
-
-Inside an Agent context (OPENCLAW_HOME / HERMES_HOME set) this command`
-
-	configInitBindGuidance = `
-refuses by default — use 'lark-cli config bind' to bind to the Agent's
-existing app instead of creating a parallel one.`
-
-	configInitBindFallback = `
-refuses by default to avoid creating a parallel app alongside Agent-managed
-credentials. Reuse the Agent's existing app through this distribution's
-supported setup flow.`
-
-	configInitBindSuffix = ` Pass --force-init only
-if the user explicitly wants a separate app inside the Agent workspace.`
-
-	configInitFallbackSuffix = ` Pass --force-init only if the user explicitly wants a
-separate app inside the Agent workspace.`
-
-	configInitLongWithBind    = configInitLongPrefix + configInitBindGuidance + configInitBindSuffix
-	configInitLongWithoutBind = configInitLongPrefix + configInitBindFallback + configInitFallbackSuffix
-
-	forceInitUsageWithBind = "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app"
-
-	forceInitUsageWithoutBind = "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME) only when the user explicitly wants a separate app"
-)
-
 // NewCmdConfigInit creates the config init subcommand.
 func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *cobra.Command {
 	opts := &ConfigInitOptions{Factory: f, UILang: i18n.LangZhCN}
@@ -86,7 +54,16 @@ func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Initialize configuration (app-id / app-secret-stdin / brand)",
-		Long:  configInitLongWithBind,
+		Long: `Initialize configuration (app-id / app-secret-stdin / brand).
+
+For AI agents: use --new to create a new app. The command blocks until the user
+completes setup in the browser. Run it in the background and retrieve the
+verification URL from its output.
+
+Inside an Agent context (OPENCLAW_HOME / HERMES_HOME set) this command
+refuses by default — use 'lark-cli config bind' to bind to the Agent's
+existing app instead of creating a parallel one. Pass --force-init only
+if the user explicitly wants a separate app inside the Agent workspace.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
 			opts.langExplicit = cmd.Flags().Changed("lang")
@@ -109,30 +86,12 @@ func NewCmdConfigInit(f *cmdutil.Factory, runF func(*ConfigInitOptions) error) *
 	cmd.Flags().StringVar(&opts.Brand, "brand", "feishu", "feishu or lark (non-interactive, default feishu)")
 	cmd.Flags().StringVar(&opts.Lang, "lang", "", "language preference (e.g. zh or zh_cn)")
 	cmd.Flags().StringVar(&opts.ProfileName, "name", "", "create or update a named profile (append instead of replace)")
-	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, forceInitUsageWithBind)
+	cmd.Flags().BoolVar(&opts.ForceInit, "force-init", false, "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app")
 	cmdutil.SetRisk(cmd, "write")
 
 	return cmd
 }
 
-// ProjectInitHelp keeps the default command-specific guidance intact and
-// replaces it only when this build conceals config bind. The config package
-// owns both variants; the root presentation pass supplies the build-local
-// availability decision after plugin policy has finalized the command tree.
-func ProjectInitHelp(cmd *cobra.Command, canReferenceBind bool) {
-	if cmd == nil {
-		return
-	}
-	long, forceInitUsage := configInitLongWithBind, forceInitUsageWithBind
-	if !canReferenceBind {
-		long, forceInitUsage = configInitLongWithoutBind, forceInitUsageWithoutBind
-	}
-	cmd.Long = long
-	if flag := cmd.Flags().Lookup("force-init"); flag != nil {
-		flag.Usage = forceInitUsage
-	}
-}
-
 // printLangPreferenceConfirmation echoes the set preference to stderr, only
 // when --lang explicitly set a non-empty value.
 func printLangPreferenceConfirmation(opts *ConfigInitOptions) {
@@ -166,14 +125,9 @@ func guardAgentWorkspace(opts *ConfigInitOptions) error {
 	if ws.IsLocal() {
 		return nil
 	}
-	return recovery.Attach(
-		errs.NewConfigError(errs.SubtypeNotConfigured,
-			"config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)", ws.Display(), ws.Display()),
-		recovery.Join(" ",
-			recovery.Command(recovery.TargetConfigBind, "see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead."),
-			recovery.Text("Pass --force-init only if the user explicitly wants a separate app in this workspace."),
-		),
-	)
+	return errs.NewConfigError(errs.SubtypeNotConfigured,
+		"config init is refused inside %s context (would create a parallel app and shadow the existing %s binding)", ws.Display(), ws.Display()).
+		WithHint("see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace.")
 }
 
 // hasAnyNonInteractiveFlag returns true if any non-interactive flag is set.

cmd/config/init_guard_test.go

@@ -9,8 +9,6 @@ import (
 	"testing"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 )
 
 func TestGuardAgentWorkspace_LocalAllows(t *testing.T) {
@@ -46,82 +44,6 @@ func TestGuardAgentWorkspace_OpenClawRefuses(t *testing.T) {
 	}
 }
 
-func TestGuardAgentWorkspace_BindRecoveryUsesBuildLocalSurface(t *testing.T) {
-	t.Setenv("OPENCLAW_HOME", t.TempDir())
-
-	source := guardAgentWorkspace(&ConfigInitOptions{})
-	var original *errs.ConfigError
-	if !errors.As(source, &original) {
-		t.Fatalf("guardAgentWorkspace() error = %T, want *errs.ConfigError", source)
-	}
-	const visibleHint = "see `lark-cli config bind --help` to bind lark-cli to the Agent's existing app instead. Pass --force-init only if the user explicitly wants a separate app in this workspace."
-	if original.Hint != visibleHint {
-		t.Fatalf("producer hint = %q, want %q", original.Hint, visibleHint)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandConfigBind: surface.CommandConcealed,
-	})
-	var concealed *errs.ConfigError
-	if rendered := recovery.Render(source, plan); !errors.As(rendered, &concealed) {
-		t.Fatalf("rendered error = %T, want *errs.ConfigError", rendered)
-	}
-	const forceInitHint = "Pass --force-init only if the user explicitly wants a separate app in this workspace."
-	if concealed.Hint != forceInitHint {
-		t.Errorf("concealed hint = %q, want %q", concealed.Hint, forceInitHint)
-	}
-	if original.Hint != visibleHint {
-		t.Errorf("concealed render mutated producer hint: %q", original.Hint)
-	}
-}
-
-func TestProjectInitHelpPreservesDefaultAndProjectsConcealedBind(t *testing.T) {
-	cmd := NewCmdConfigInit(nil, nil)
-	forceInit := cmd.Flags().Lookup("force-init")
-	if forceInit == nil {
-		t.Fatal("config init command has no --force-init flag")
-	}
-	const defaultLong = `Initialize configuration (app-id / app-secret-stdin / brand).
-
-For AI agents: use --new to create a new app. The command blocks until the user
-completes setup in the browser. Run it in the background and retrieve the
-verification URL from its output.
-
-Inside an Agent context (OPENCLAW_HOME / HERMES_HOME set) this command
-refuses by default — use 'lark-cli config bind' to bind to the Agent's
-existing app instead of creating a parallel one. Pass --force-init only
-if the user explicitly wants a separate app inside the Agent workspace.`
-	const defaultForceInitUsage = "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME); use config bind instead unless you really want a separate app"
-	if cmd.Long != defaultLong || forceInit.Usage != defaultForceInitUsage {
-		t.Fatalf("default help lost config bind recovery:\nLong:\n%s\n--force-init: %s", cmd.Long, forceInit.Usage)
-	}
-
-	ProjectInitHelp(cmd, false)
-	const concealedLong = `Initialize configuration (app-id / app-secret-stdin / brand).
-
-For AI agents: use --new to create a new app. The command blocks until the user
-completes setup in the browser. Run it in the background and retrieve the
-verification URL from its output.
-
-Inside an Agent context (OPENCLAW_HOME / HERMES_HOME set) this command
-refuses by default to avoid creating a parallel app alongside Agent-managed
-credentials. Reuse the Agent's existing app through this distribution's
-supported setup flow. Pass --force-init only if the user explicitly wants a
-separate app inside the Agent workspace.`
-	const concealedForceInitUsage = "allow init inside an Agent workspace (OPENCLAW_HOME / HERMES_HOME) only when the user explicitly wants a separate app"
-	if cmd.Long != concealedLong || forceInit.Usage != concealedForceInitUsage {
-		t.Fatalf("concealed help was not projected:\nLong:\n%s\n--force-init: %s", cmd.Long, forceInit.Usage)
-	}
-	if strings.Contains(cmd.Long, "config bind") || strings.Contains(forceInit.Usage, "config bind") {
-		t.Fatalf("concealed help retained config bind:\nLong:\n%s\n--force-init: %s", cmd.Long, forceInit.Usage)
-	}
-
-	ProjectInitHelp(cmd, true)
-	if cmd.Long != defaultLong || forceInit.Usage != defaultForceInitUsage {
-		t.Fatalf("visible projection did not restore default help:\nLong:\n%s\n--force-init: %s", cmd.Long, forceInit.Usage)
-	}
-}
-
 func TestGuardAgentWorkspace_HermesRefuses(t *testing.T) {
 	t.Setenv("HERMES_HOME", t.TempDir())
 

cmd/config/plugins.go

@@ -27,13 +27,6 @@ func NewCmdConfigPlugins(f *cmdutil.Factory) *cobra.Command {
 		Use:    "plugins",
 		Hidden: true, // diagnostic-only; kept callable, omitted from --help so it stays out of AI-agent context
 		Short:  "Inspect installed plugins and their hook contributions",
-		// Same leaf-level no-op as config policy: the parent `config`
-		// group's PersistentPreRunE requires builtin credential, but
-		// this is a read-only diagnostic that must work everywhere.
-		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
-			c.SilenceUsage = true
-			return nil
-		},
 	}
 	cmd.AddCommand(newCmdConfigPluginsShow(f))
 	return cmd
@@ -85,9 +78,6 @@ func runConfigPluginsShow(f *cmdutil.Factory) error {
 		if len(p.Rules) > 0 {
 			entry["rules"] = p.Rules
 		}
-		if p.EmbeddedSkills != nil {
-			entry["embedded_skills"] = p.EmbeddedSkills
-		}
 		entry["hooks"] = map[string]any{
 			"observers": p.Observers,
 			"wrappers":  p.Wrappers,

cmd/config/plugins_test.go

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

cmd/config/policy.go

@@ -16,12 +16,6 @@ func NewCmdConfigPolicy(f *cmdutil.Factory) *cobra.Command {
 		Use:    "policy",
 		Hidden: true,
 		Short:  "Inspect the user-layer command policy",
-		// Override parent's RequireBuiltinCredentialProvider check; this
-		// group is read-only diagnostic and must work under any provider.
-		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
-			c.SilenceUsage = true
-			return nil
-		},
 	}
 	cmd.AddCommand(newCmdConfigPolicyShow(f))
 	return cmd
@@ -57,7 +51,7 @@ func runConfigPolicyShow(f *cmdutil.Factory) error {
 	out := map[string]any{
 		"source":       string(active.Source.Kind),
 		"source_name":  sourceName,
-		"denied_paths": active.DeniedPathCount(),
+		"denied_paths": active.DeniedPaths,
 	}
 	if len(active.Rules) > 0 {
 		rules := make([]map[string]any, 0, len(active.Rules))

cmd/config/policy_test.go

@@ -62,10 +62,7 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 			Kind: cmdpolicy.SourcePlugin,
 			Name: "secaudit",
 		},
-		DeniedByPath: map[string]cmdpolicy.Denial{
-			"docs/create": {},
-			"docs/update": {},
-		},
+		DeniedPaths: 42,
 	})
 
 	f, out, _ := newPolicyTestFactory()
@@ -83,8 +80,8 @@ func TestConfigPolicyShow_PluginActive(t *testing.T) {
 		t.Errorf("source_name = %v, want secaudit", got["source_name"])
 	}
 	// json.Unmarshal returns float64 for numbers.
-	if got["denied_paths"] != float64(2) {
-		t.Errorf("denied_paths = %v, want 2", got["denied_paths"])
+	if got["denied_paths"] != float64(42) {
+		t.Errorf("denied_paths = %v, want 42", got["denied_paths"])
 	}
 	rulesAny, ok := got["rules"].([]any)
 	if !ok || len(rulesAny) != 1 {
@@ -135,19 +132,16 @@ func TestConfigPolicyShow_YamlSourceNameIsEmpty(t *testing.T) {
 	}
 }
 
-// Regression: the parent `config` command declares a PersistentPreRunE
-// that calls RequireBuiltinCredentialProvider; env credentials cause
-// it to return external_provider. `config policy` is a diagnostic
-// group that must not be blocked by that check. The group declares
-// its own no-op PersistentPreRunE so cobra's "first walking up from
-// leaf" picks ours over the config parent's.
-func TestConfigPolicy_BypassesConfigParentPersistentPreRunE(t *testing.T) {
+// The policy group explicitly overrides the config parent's local credential
+// management capability because it is source-neutral diagnostics.
+func TestConfigPolicyOverridesCredentialManagementCapability(t *testing.T) {
 	f, _, _ := newPolicyTestFactory()
-	group := NewCmdConfigPolicy(f)
-	if group.PersistentPreRunE == nil {
-		t.Fatal("config policy group must declare its own PersistentPreRunE to win over config parent")
+	root := NewCmdConfig(f)
+	leaf, _, err := root.Find([]string{"policy", "show"})
+	if err != nil {
+		t.Fatal(err)
 	}
-	if err := group.PersistentPreRunE(group, nil); err != nil {
-		t.Errorf("config policy PersistentPreRunE should be no-op, got %v", err)
+	if capabilities := cmdutil.GetRuntimeCapabilities(leaf); len(capabilities) != 0 {
+		t.Fatalf("policy capabilities = %v, want source-neutral", capabilities)
 	}
 }

cmd/config/risk_control.go

@@ -23,11 +23,6 @@ func NewCmdConfigRiskControl(f *cmdutil.Factory) *cobra.Command {
 Account protection is on by default. Use off to opt this workspace out, on to
 opt it back in explicitly, or default to remove the explicit preference.`,
 		Args: cobra.MaximumNArgs(1),
-		// This is persistent workspace policy, not credential management.
-		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
-			cmd.SilenceUsage = true
-			return nil
-		},
 		RunE: func(cmd *cobra.Command, args []string) error {
 			config, err := core.LoadOrNotConfigured()
 			if err != nil {

cmd/config/show.go

@@ -13,7 +13,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/spf13/cobra"
 )
 
@@ -43,6 +42,16 @@ func NewCmdConfigShow(f *cmdutil.Factory, runF func(*ConfigShowOptions) error) *
 
 func configShowRun(opts *ConfigShowOptions) error {
 	f := opts.Factory
+	// config show describes the effective invocation configuration, not merely
+	// the bytes in config.json. Preserve the typed bootstrap failure so a
+	// Standard binary cannot present a local Profile as active when the system
+	// requires Extended runtime support.
+	if startupErr := f.RuntimeStartupError(); startupErr != nil {
+		return startupErr
+	}
+	if handled, editionErr := showEditionConfig(f); handled {
+		return editionErr
+	}
 
 	config, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -56,14 +65,7 @@ func configShowRun(opts *ConfigShowOptions) error {
 	}
 	app := config.CurrentAppConfig(f.Invocation.Profile)
 	if app == nil {
-		hint := recovery.Join("",
-			recovery.Command(recovery.TargetProfileList, "run: lark-cli profile list")).
-			WithFallback("select or configure an available profile through this distribution")
-		return recovery.Annotate(
-			errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile").
-				WithHint("%s", hint.String()),
-			hint,
-		)
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "no active profile").WithHint("run: lark-cli profile list")
 	}
 	users := "(no logged-in users)"
 	if len(app.Users) > 0 {

cmd/config/show_edition_extended.go

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package config
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/output"
+)
+
+type editionConfigShowResult struct {
+	Source                 string  `json:"source"`
+	CredentialProvider     string  `json:"credentialProvider"`
+	Manageable             bool    `json:"manageable"`
+	Workspace              string  `json:"workspace"`
+	AppID                  string  `json:"appId"`
+	Brand                  string  `json:"brand"`
+	DefaultAs              string  `json:"defaultAs"`
+	Profile                *string `json:"profile,omitempty"`
+	ExternalCredentialMode *string `json:"externalCredentialMode,omitempty"`
+	RemoteEndpoint         *string `json:"remoteEndpoint,omitempty"`
+}
+
+func showEditionConfig(f *cmdutil.Factory) (bool, error) {
+	if f == nil || f.Credential == nil {
+		return false, nil
+	}
+	source, err := f.Credential.InspectSource(context.Background())
+	if err != nil {
+		return true, typedEditionProviderError("determine the active credential provider", err)
+	}
+	if source == nil || !source.Managed {
+		return false, nil
+	}
+	if source.AppID == "" {
+		return true, errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"external credential provider %q returned no account", source.Name)
+	}
+	result := editionConfigShowResult{
+		Source:             "external",
+		CredentialProvider: source.Name,
+		Manageable:         false,
+		Workspace:          core.CurrentWorkspace().Display(),
+		AppID:              source.AppID,
+		Brand:              string(source.Brand),
+		DefaultAs:          string(source.DefaultAs),
+	}
+	description := f.RuntimeDescription()
+	if source.ProfileName != "" {
+		result.Profile = &source.ProfileName
+	}
+	if description.Managed && description.Variant != "" {
+		result.ExternalCredentialMode = &description.Variant
+		if description.ProxiesRequests {
+			result.RemoteEndpoint = &description.DataPlaneEndpoint
+		}
+	}
+	output.PrintJson(f.IOStreams.Out, result)
+	return true, nil
+}
+
+func typedEditionProviderError(action string, err error) error {
+	if _, ok := errs.ProblemOf(err); ok {
+		return err
+	}
+	return errs.NewInternalError(errs.SubtypeUnknown, "failed to %s: %v", action, err).WithCause(err)
+}

cmd/config/show_edition_extended_test.go

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package config
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/runtimeplan"
+)
+
+func TestExtendedConfigShowAllowedWithManagedSource(t *testing.T) {
+	f := newConfigFactoryWithExternalProvider(t)
+	cmd := NewCmdConfig(f)
+	matched, _, err := cmd.Find([]string{"show"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.PersistentPreRunE(matched, nil); err != nil {
+		t.Fatalf("config show blocked: %v", err)
+	}
+}
+
+func TestExtendedConfigShowProjectsManagedSource(t *testing.T) {
+	f := newConfigFactoryWithExternalProvider(t)
+	var stdout bytes.Buffer
+	f.IOStreams.Out = &stdout
+	cmdutil.TestSetRuntimePlan(t, f, runtimeplan.New(runtimeplan.Options{
+		Description: runtimeplan.Description{
+			Managed:           true,
+			Variant:           "managed-test",
+			ProxiesRequests:   true,
+			DataPlaneEndpoint: "https://managed.example.test",
+		},
+	}))
+
+	if err := configShowRun(&ConfigShowOptions{Factory: f}); err != nil {
+		t.Fatalf("configShowRun() error = %v", err)
+	}
+	var got editionConfigShowResult
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Source != "external" ||
+		got.CredentialProvider != "env" ||
+		got.Manageable ||
+		got.AppID != "test-app" ||
+		got.ExternalCredentialMode == nil ||
+		*got.ExternalCredentialMode != "managed-test" ||
+		got.RemoteEndpoint == nil ||
+		*got.RemoteEndpoint != "https://managed.example.test" {
+		t.Fatalf("output = %#v", got)
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(stdout.Bytes(), &fields); err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := fields["appSecret"]; ok {
+		t.Fatalf("managed output must not invent appSecret: %s", stdout.String())
+	}
+	if _, ok := fields["users"]; ok {
+		t.Fatalf("managed output must not invent users: %s", stdout.String())
+	}
+}
+
+func TestExtendedConfigShowTypesManagedSourceFailure(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	providerErr := errors.New("provider failed")
+	cred := credential.NewCredentialProvider(
+		[]extcred.Provider{&stubConfigExtProvider{name: "broken", err: providerErr}},
+		nil, nil, nil,
+	)
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	f.Credential = cred
+
+	err := configShowRun(&ConfigShowOptions{Factory: f})
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("error = %#v, want internal/unknown", err)
+	}
+	if !errors.Is(err, providerErr) {
+		t.Fatalf("error does not preserve provider failure: %v", err)
+	}
+}

cmd/config/show_edition_standard.go

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package config
+
+import "github.com/larksuite/cli/internal/cmdutil"
+
+func showEditionConfig(*cmdutil.Factory) (bool, error) {
+	return false, nil
+}

cmd/config/show_edition_standard_test.go

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package config
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/runtimeplan"
+)
+
+func TestStandardConfigShowPreservesLocalConfigPath(t *testing.T) {
+	f := newConfigFactoryWithExternalProvider(t)
+
+	err := configShowRun(&ConfigShowOptions{Factory: f})
+	problem, ok := errs.ProblemOf(err)
+	if !ok ||
+		problem.Category != errs.CategoryConfig ||
+		problem.Subtype != errs.SubtypeNotConfigured {
+		t.Fatalf("error = %#v, want established config/not_configured result", err)
+	}
+}
+
+func TestStandardConfigShowReturnsTypedRuntimeStartupError(t *testing.T) {
+	startupErr := errs.NewValidationError(
+		errs.SubtypeFailedPrecondition,
+		"system external credential configuration requires the lark-cli Extended edition",
+	).WithHint("install lark-cli Extended or ask the administrator to remove external-credential.json")
+	f, stdout, _, _ := cmdutil.TestFactoryWithRuntimePlan(
+		t,
+		nil,
+		runtimeplan.Failed(startupErr, runtimeplan.MetadataEmbeddedOnly),
+	)
+
+	err := configShowRun(&ConfigShowOptions{Factory: f})
+	if !errors.Is(err, startupErr) {
+		t.Fatalf("config show error = %v, want original startup error", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok ||
+		problem.Category != errs.CategoryValidation ||
+		problem.Subtype != errs.SubtypeFailedPrecondition ||
+		problem.Message != "system external credential configuration requires the lark-cli Extended edition" {
+		t.Fatalf("config show problem = %#v, want typed Extended-required startup failure", problem)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("config show wrote local Profile after bootstrap failure: %s", stdout.String())
+	}
+}

cmd/doctor/doctor.go

@@ -20,7 +20,6 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/update"
 )
@@ -34,17 +33,6 @@ type DoctorOptions struct {
 
 // NewCmdDoctor creates the doctor command.
 func NewCmdDoctor(f *cmdutil.Factory) *cobra.Command {
-	return newCmdDoctor(f, nil)
-}
-
-// NewCmdDoctorWithRecovery creates the doctor command with a build-local
-// recovery presenter. Distribution assembly uses this boundary; ordinary
-// callers keep NewCmdDoctor's original function signature and default output.
-func NewCmdDoctorWithRecovery(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
-	return newCmdDoctor(f, projector)
-}
-
-func newCmdDoctor(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
 	opts := &DoctorOptions{Factory: f}
 
 	cmd := &cobra.Command{
@@ -52,7 +40,7 @@ func newCmdDoctor(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Comm
 		Short: "CLI health check: config, auth, and connectivity",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Ctx = cmd.Context()
-			return doctorRun(opts, projector)
+			return doctorRun(opts)
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
@@ -86,16 +74,20 @@ func skip(name, msg string) checkResult {
 	return checkResult{Name: name, Status: "skip", Message: msg}
 }
 
-func doctorRun(opts *DoctorOptions, projector *recovery.Projector) error {
+func doctorRun(opts *DoctorOptions) error {
 	f := opts.Factory
 	var checks []checkResult
 
 	// ── 0. CLI version & update check ──
 	checks = append(checks, pass("cli_version", build.Version))
-	if !opts.Offline && projector.CanReference(recovery.TargetUpdate) {
+	if !opts.Offline {
 		checks = append(checks, checkCLIUpdate()...)
 	}
 
+	if handled, editionErr := runEditionDoctor(opts, checks); handled {
+		return editionErr
+	}
+
 	// ── 1. Config file ──
 	_, err := core.LoadMultiAppConfig()
 	if err != nil {
@@ -108,7 +100,7 @@ func doctorRun(opts *DoctorOptions, projector *recovery.Projector) error {
 		msg, hint := err.Error(), ""
 		if errors.Is(err, os.ErrNotExist) {
 			var cfgErr *errs.ConfigError
-			if errors.As(projector.Render(core.NotConfiguredError()), &cfgErr) {
+			if errors.As(core.NotConfiguredError(), &cfgErr) {
 				msg, hint = cfgErr.Message, cfgErr.Hint
 			}
 		}
@@ -122,7 +114,7 @@ func doctorRun(opts *DoctorOptions, projector *recovery.Projector) error {
 	if err != nil {
 		hint := ""
 		var cfgErr *errs.ConfigError
-		if errors.As(projector.Render(err), &cfgErr) {
+		if errors.As(err, &cfgErr) {
 			hint = cfgErr.Hint
 		}
 		checks = append(checks, fail("app_resolved", err.Error(), hint))
@@ -133,10 +125,7 @@ func doctorRun(opts *DoctorOptions, projector *recovery.Projector) error {
 	ep := core.ResolveEndpoints(cfg.Brand)
 
 	// ── 3. Identity readiness ──
-	diagnostics := identitydiag.FilterRecovery(
-		identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline),
-		projector.CanReference,
-	)
+	diagnostics := identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline)
 	checks = append(checks,
 		identityCheck("bot_identity", diagnostics.Bot),
 		identityCheck("user_identity", diagnostics.User),
@@ -145,8 +134,7 @@ func doctorRun(opts *DoctorOptions, projector *recovery.Projector) error {
 		checks = append(checks, pass("identity_ready", "at least one identity is available"))
 	} else {
 		// No hint: this only summarizes the two checks above, which already carry
-		// the source-appropriate remediation. A command here would be redundant,
-		// or wrong (`auth status` is blocked under an external provider).
+		// the source-appropriate remediation. A command here would be redundant.
 		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
 	}
 
@@ -230,7 +218,7 @@ func probeEndpoint(ctx context.Context, client *http.Client, url string) error {
 // Unlike the root-level async check, this does a synchronous fetch with timeout
 // and works regardless of build version (dev builds included).
 func checkCLIUpdate() []checkResult {
-	latest, err := fetchLatestForDoctor()
+	latest, err := fetchLatestForEdition()
 	if err != nil {
 		return []checkResult{warn("cli_update", "check failed: "+err.Error(), "")}
 	}
@@ -243,8 +231,6 @@ func checkCLIUpdate() []checkResult {
 	return []checkResult{pass("cli_update", latest+" (up to date)")}
 }
 
-var fetchLatestForDoctor = update.FetchLatest
-
 func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 	allOK := true
 	for _, c := range checks {

cmd/doctor/doctor_edition_extended.go

@@ -0,0 +1,94 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package doctor
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/identitydiag"
+)
+
+func runEditionDoctor(opts *DoctorOptions, checks []checkResult) (bool, error) {
+	f := opts.Factory
+	if f == nil || f.Credential == nil {
+		return false, nil
+	}
+	source, err := f.Credential.InspectSource(opts.Ctx)
+	if err != nil {
+		checks = append(checks, fail("credential_source", err.Error(), editionDiagnosticErrorHint(err)))
+		return true, finishDoctor(f, checks)
+	}
+	if source == nil || !source.Managed {
+		return false, nil
+	}
+
+	provider := source.Name
+	cfg, err := f.Config()
+	if err != nil {
+		checks = append(checks,
+			fail("credential_source", err.Error(), editionDiagnosticErrorHint(err)),
+			skip("config_file", fmt.Sprintf("local credentials are not used; source is %s", provider)),
+		)
+		return true, finishDoctor(f, checks)
+	}
+	checks = append(checks, pass("credential_source",
+		fmt.Sprintf("credentials provided by %s (app %s; token not verified by this check)", provider, cfg.AppID)))
+
+	description := f.RuntimeDescription()
+	if description.Managed {
+		checks = append(checks, pass("config_file", "config.json found (system external credential mode)"))
+	} else {
+		checks = append(checks, skip("config_file",
+			fmt.Sprintf("local config not used; credentials provided by %s", provider)))
+	}
+	checks = append(checks, pass("app_resolved", fmt.Sprintf("app: %s (%s)", cfg.AppID, cfg.Brand)))
+
+	diagnostics := identitydiag.Diagnose(opts.Ctx, f, cfg, !opts.Offline)
+	checks = append(checks,
+		identityCheck("bot_identity", diagnostics.Bot),
+		identityCheck("user_identity", diagnostics.User),
+	)
+	if diagnostics.Bot.Available || diagnostics.User.Available {
+		checks = append(checks, pass("identity_ready", "at least one identity is available"))
+	} else {
+		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
+	}
+
+	if description.ProxiesRequests {
+		checks = append(checks, editionProxyNetworkCheck(opts, description.DataPlaneEndpoint, diagnostics))
+	} else {
+		checks = append(checks, networkChecks(opts.Ctx, opts, core.ResolveEndpoints(cfg.Brand))...)
+	}
+	return true, finishDoctor(f, checks)
+}
+
+func editionDiagnosticErrorHint(err error) string {
+	var blockErr *extcred.BlockError
+	if errors.As(err, &blockErr) {
+		return blockErr.Reason
+	}
+	var cfgErr *errs.ConfigError
+	if errors.As(err, &cfgErr) {
+		return cfgErr.Hint
+	}
+	return ""
+}
+
+func editionProxyNetworkCheck(opts *DoctorOptions, endpoint string, diagnostics identitydiag.Result) checkResult {
+	if opts.Offline {
+		return skip("endpoint_external_platform", "skipped (--offline)")
+	}
+	verified := func(id identitydiag.Identity) bool { return id.Verified != nil && *id.Verified }
+	if verified(diagnostics.User) || verified(diagnostics.Bot) {
+		return pass("endpoint_external_platform", endpoint+" reachable through an authenticated API request")
+	}
+	return fail("endpoint_external_platform", endpoint+" could not complete an authenticated API request",
+		"check the external credential program and platform logs")
+}

cmd/doctor/doctor_edition_extended_test.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package doctor
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/identitydiag"
+)
+
+func TestExtendedProxyNetworkCheckUsesAuthenticatedDiagnostics(t *testing.T) {
+	verified := true
+	endpoint := "https://credentials.example.com"
+	got := editionProxyNetworkCheck(&DoctorOptions{}, endpoint, identitydiag.Result{
+		User: identitydiag.Identity{Verified: &verified},
+	})
+	if got.Status != "pass" || got.Name != "endpoint_external_platform" {
+		t.Fatalf("check = %#v", got)
+	}
+
+	got = editionProxyNetworkCheck(&DoctorOptions{}, endpoint, identitydiag.Result{})
+	if got.Status != "fail" {
+		t.Fatalf("unverified check = %#v, want fail", got)
+	}
+}
+
+func TestExtendedDoctorManagedSourceDoesNotRequireLocalConfig(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := &core.CliConfig{
+		AppID: "cli_env", Brand: core.BrandFeishu,
+		SupportedIdentities: uint8(extcred.SupportsBot), DefaultAs: core.AsBot,
+	}
+	f, out, _, _ := cmdutil.TestFactory(t, cfg)
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{&fakeExtProvider{
+			name: "env",
+			account: &extcred.Account{
+				AppID:               "cli_env",
+				SupportedIdentities: extcred.SupportsBot,
+			},
+		}},
+		nil, nil, nil,
+	)
+
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err != nil {
+		t.Fatalf("doctorRun() error = %v", err)
+	}
+	var got struct {
+		OK     bool          `json:"ok"`
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if !got.OK {
+		t.Fatalf("checks = %#v", got.Checks)
+	}
+	assertCheck(t, got.Checks, "credential_source", "pass")
+	configCheck := findCheck(t, got.Checks, "config_file")
+	if configCheck.Status != "skip" ||
+		!strings.Contains(configCheck.Message, "local config") ||
+		strings.Contains(configCheck.Message, "config init") {
+		t.Fatalf("config_file = %#v", configCheck)
+	}
+}

cmd/doctor/doctor_edition_standard.go

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package doctor
+
+import "github.com/larksuite/cli/errs"
+
+func runEditionDoctor(opts *DoctorOptions, checks []checkResult) (bool, error) {
+	if opts == nil || opts.Factory == nil {
+		return false, nil
+	}
+	startupErr := opts.Factory.RuntimeStartupError()
+	if startupErr == nil {
+		return false, nil
+	}
+	hint := ""
+	if problem, ok := errs.ProblemOf(startupErr); ok {
+		hint = problem.Hint
+	}
+	checks = append(checks, fail("credential_source", startupErr.Error(), hint))
+	return true, finishDoctor(opts.Factory, checks)
+}

cmd/doctor/doctor_edition_standard_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package doctor
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+)
+
+func TestStandardDoctorPreservesConfigFirstDiagnostics(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := &core.CliConfig{
+		AppID: "cli_env", Brand: core.BrandFeishu,
+		SupportedIdentities: uint8(extcred.SupportsBot), DefaultAs: core.AsBot,
+	}
+	f, out, _, _ := cmdutil.TestFactory(t, cfg)
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{&fakeExtProvider{
+			name: "env",
+			account: &extcred.Account{
+				AppID:               "cli_env",
+				SupportedIdentities: extcred.SupportsBot,
+			},
+		}},
+		nil, nil, nil,
+	)
+
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
+		t.Fatal("doctorRun() = nil, want established missing-config failure")
+	}
+	var got struct {
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	assertCheck(t, got.Checks, "config_file", "fail")
+	for _, check := range got.Checks {
+		if check.Name == "credential_source" {
+			t.Fatalf("Standard doctor exposed edition diagnostic: %#v", got.Checks)
+		}
+	}
+}

cmd/doctor/doctor_test.go

@@ -4,7 +4,6 @@
 package doctor
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"net/http"
@@ -17,8 +16,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 )
 
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
@@ -103,31 +100,6 @@ func TestNetworkChecks_Offline(t *testing.T) {
 	}
 }
 
-func TestDoctorRunDoesNotFetchUpdateWhenCommandIsConcealed(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	oldFetch := fetchLatestForDoctor
-	t.Cleanup(func() { fetchLatestForDoctor = oldFetch })
-
-	fetches := 0
-	fetchLatestForDoctor = func() (string, error) {
-		fetches++
-		return "9.9.9", nil
-	}
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandUpdate: surface.CommandConcealed,
-	})
-	projector := recovery.NewProjector(func() *surface.Plan { return plan })
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-
-	_ = doctorRun(&DoctorOptions{
-		Factory: f,
-		Ctx:     context.Background(),
-	}, projector)
-	if fetches != 0 {
-		t.Fatalf("concealed update triggered %d npm fetch(es)", fetches)
-	}
-}
-
 func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
@@ -151,7 +123,7 @@ func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
 		Factory: f,
 		Ctx:     context.Background(),
 		Offline: true,
-	}, nil)
+	})
 	if err != nil {
 		t.Fatalf("doctorRun() error = %v", err)
 	}
@@ -202,6 +174,44 @@ func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*ext
 	return nil, nil
 }
 
+type failingDefaultAccountResolver struct {
+	err error
+}
+
+func (r *failingDefaultAccountResolver) ResolveAccount(context.Context) (*credential.Account, error) {
+	return nil, r.err
+}
+
+func TestDoctor_DefaultResolutionFailurePreservesConfigFileCheck(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, out, _, _ := cmdutil.TestFactory(t, nil)
+	f.Credential = credential.NewCredentialProvider(
+		nil,
+		&failingDefaultAccountResolver{err: core.NotConfiguredError()},
+		nil,
+		nil,
+	)
+
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
+		t.Fatal("doctorRun() = nil, want not-configured failure")
+	}
+	var got struct {
+		Checks []checkResult `json:"checks"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v\n%s", err, out.String())
+	}
+	configCheck := findCheck(t, got.Checks, "config_file")
+	if configCheck.Status != "fail" {
+		t.Fatalf("config_file = %#v, want fail", configCheck)
+	}
+	for _, check := range got.Checks {
+		if check.Name == "credential_source" {
+			t.Fatalf("default source resolution replaced the legacy config check: %#v", got.Checks)
+		}
+	}
+}
+
 // Under an external credential provider with no usable identity, the
 // identity_ready hint must not point at `auth status` (blocked there); the
 // per-identity checks already carry the source-appropriate escalation.
@@ -222,14 +232,10 @@ func TestDoctor_ExternalProvider_IdentityReadyHintNotBlockedCommand(t *testing.T
 		nil, nil,
 		func() (*http.Client, error) { return nil, nil },
 	)
-	out := &bytes.Buffer{}
-	f := &cmdutil.Factory{
-		Config:     func() (*core.CliConfig, error) { return cfg, nil },
-		Credential: cred,
-		IOStreams:  &cmdutil.IOStreams{Out: out, ErrOut: &bytes.Buffer{}},
-	}
+	f, out, _, _ := cmdutil.TestFactory(t, cfg)
+	f.Credential = cred
 
-	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}, nil); err == nil {
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
 		t.Fatalf("doctorRun() = nil, want failure when no identity is available")
 	}
 	var got struct {

cmd/doctor/update_extended.go

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package doctor
+
+import "github.com/larksuite/cli/internal/extendedupdate"
+
+func fetchLatestForEdition() (string, error) {
+	return extendedupdate.FetchLatest()
+}

cmd/doctor/update_standard.go

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package doctor
+
+import "github.com/larksuite/cli/internal/update"
+
+func fetchLatestForEdition() (string, error) {
+	return update.FetchLatest()
+}

cmd/doctor_startup_standard_test.go

@@ -0,0 +1,74 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/envvars"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+func TestStandardDoctorReportsEditionSentinelWithoutLocalProfile(t *testing.T) {
+	clearWorkspaceSignals(t)
+	clearCredentialSignals(t)
+	configDir := t.TempDir()
+	systemPath := filepath.Join(configDir, "external-credential.json")
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+	t.Setenv(envvars.CliExternalCredentialConfig, systemPath)
+	t.Setenv("LARKSUITE_CLI_REMOTE_META", "off")
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
+	t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
+	if err := vfs.WriteFile(systemPath, []byte("sentinel-only"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	root := Build(
+		context.Background(),
+		cmdutil.InvocationContext{},
+		WithIO(strings.NewReader(""), &stdout, &stderr),
+		WithoutPlugins(),
+		WithoutServiceCommands(),
+	)
+	root.SetArgs([]string{"doctor", "--offline"})
+	if err := root.ExecuteContext(context.Background()); err == nil {
+		t.Fatal("doctor returned nil, want failed diagnostic result")
+	}
+
+	var report struct {
+		Checks []struct {
+			Name    string `json:"name"`
+			Status  string `json:"status"`
+			Message string `json:"message"`
+			Hint    string `json:"hint"`
+		} `json:"checks"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &report); err != nil {
+		t.Fatalf("decode doctor output: %v\nstdout: %s\nstderr: %s", err, stdout.String(), stderr.String())
+	}
+	for _, check := range report.Checks {
+		if check.Name != "credential_source" {
+			continue
+		}
+		if check.Status != "fail" ||
+			check.Message != "system external credential configuration requires the lark-cli Extended edition" ||
+			!strings.Contains(check.Hint, "install lark-cli Extended") {
+			t.Fatalf("credential_source check = %#v", check)
+		}
+		if strings.Contains(stdout.String(), "config init") {
+			t.Fatalf("doctor suggested local credential bootstrap for an edition sentinel: %s", stdout.String())
+		}
+		return
+	}
+	t.Fatalf("doctor did not report the edition sentinel: %s", stdout.String())
+}

cmd/edition_commands_extended.go

@@ -0,0 +1,17 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package cmd
+
+import (
+	cmdversion "github.com/larksuite/cli/cmd/version"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+// registerEditionCommands owns the Extended-only command surface.
+func registerEditionCommands(root *cobra.Command, f *cmdutil.Factory) {
+	root.AddCommand(cmdversion.NewCmdVersion(f))
+}

cmd/edition_commands_extended_test.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package cmd
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+func TestExtendedRegistersVersionCommand(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	root := &cobra.Command{Use: "lark-cli"}
+
+	registerEditionCommands(root, f)
+
+	commands := root.Commands()
+	if len(commands) != 1 || commands[0].Name() != "version" {
+		t.Fatalf("Extended edition commands = %v, want [version]", commands)
+	}
+	if commands[0].Hidden {
+		t.Fatal("Extended version command must be visible")
+	}
+}

cmd/edition_commands_standard.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package cmd
+
+import (
+	cmdversion "github.com/larksuite/cli/cmd/version"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+// registerEditionCommands keeps the release identity probe callable in
+// Standard while cmd/version hides it from help. This preserves the ordinary
+// command surface and gives installers/CI one edition-neutral verification
+// contract.
+func registerEditionCommands(root *cobra.Command, f *cmdutil.Factory) {
+	root.AddCommand(cmdversion.NewCmdVersion(f))
+}

cmd/edition_commands_standard_test.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package cmd
+
+import (
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+func TestStandardRegistersHiddenVersionCommand(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	root := &cobra.Command{Use: "lark-cli"}
+
+	registerEditionCommands(root, f)
+
+	commands := root.Commands()
+	if len(commands) != 1 || commands[0].Name() != "version" {
+		t.Fatalf("Standard edition commands = %v, want [version]", commands)
+	}
+	if !commands[0].Hidden {
+		t.Fatal("Standard version command must remain hidden")
+	}
+}

cmd/error_auth_hint.go

@@ -4,6 +4,7 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"strings"
 
@@ -14,64 +15,11 @@ import (
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/errclass"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/shortcuts"
 	shortcutcommon "github.com/larksuite/cli/shortcuts/common"
 )
 
-// rootErrorPresenter owns the final command-facing error transformation for
-// one Cobra tree. Producers report typed facts and optional semantic recovery;
-// this boundary clones, completes, and projects them without exposing the
-// build-local surface plan to business packages.
-type rootErrorPresenter struct {
-	f         *cmdutil.Factory
-	projector *recovery.Projector
-}
-
-func newRootErrorPresenter(f *cmdutil.Factory, projector *recovery.Projector) *rootErrorPresenter {
-	return &rootErrorPresenter{f: f, projector: projector}
-}
-
-func (p *rootErrorPresenter) Present(err error) error {
-	if err == nil || errs.IsRaw(err) {
-		return err
-	}
-	rendered := p.projector.Render(err)
-	p.completePermissionRecovery(rendered)
-	applyNeedAuthorizationHint(p.f, rendered)
-	return rendered
-}
-
-// completePermissionRecovery supplies the canonical recovery for direct
-// PermissionError producers. API classification paths that already carry an
-// owned structured annotation keep their rendered Hint unchanged.
-func (p *rootErrorPresenter) completePermissionRecovery(err error) {
-	typed, ok := errs.UnwrapTypedError(err)
-	if !ok {
-		return
-	}
-	permissionErr, ok := typed.(*errs.PermissionError) //nolint:errorlint // presentation must not descend into the clone's original Cause
-	if !ok || permissionErr.Hint != "" {
-		return
-	}
-	identity := permissionErr.Identity
-	if identity == "" && p.f != nil {
-		identity = string(p.f.ResolvedIdentity)
-	}
-	if identity == "" {
-		identity = string(core.AsUser)
-	}
-	hint := errclass.PermissionRecovery(
-		permissionErr.MissingScopes,
-		identity,
-		permissionErr.Subtype,
-		permissionErr.ConsoleURL,
-	)
-	permissionErr.Hint = p.projector.RenderHint(hint)
-}
-
 // applyNeedAuthorizationHint augments a typed *errs.AuthenticationError with a
 // "current command requires scope(s): X, Y" hint when the underlying error is
 // a need_user_authorization signal AND the current command declares scopes
@@ -84,12 +32,8 @@ func applyNeedAuthorizationHint(f *cmdutil.Factory, err error) {
 	if !internalauth.IsNeedUserAuthorizationError(err) {
 		return
 	}
-	typed, ok := errs.UnwrapTypedError(err)
-	if !ok {
-		return
-	}
-	authErr, ok := typed.(*errs.AuthenticationError) //nolint:errorlint // enrich only the presented clone, never a nested producer Cause
-	if !ok {
+	var authErr *errs.AuthenticationError
+	if !errors.As(err, &authErr) {
 		return
 	}
 	scopes := resolveDeclaredScopesForCurrentCommand(f)

cmd/error_presenter_test.go

@@ -1,139 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	internalauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/registry"
-	"github.com/larksuite/cli/internal/surface"
-	"github.com/spf13/cobra"
-)
-
-func TestRootErrorPresenterCompletesDirectPermissionRecoveryWithoutMutatingProducer(t *testing.T) {
-	source := errs.NewPermissionError(errs.SubtypeMissingScope, "missing scope").
-		WithMissingScopes("docx:document").
-		WithIdentity("user")
-
-	visible := newRootErrorPresenter(
-		&cmdutil.Factory{ResolvedIdentity: core.AsUser},
-		recovery.NewProjector(nil),
-	).Present(source)
-	visibleProblem, _ := errs.ProblemOf(visible)
-	if !strings.Contains(visibleProblem.Hint, `auth login --scope "docx:document"`) {
-		t.Fatalf("visible recovery = %q, want scoped auth login", visibleProblem.Hint)
-	}
-	if source.Hint != "" {
-		t.Fatalf("presenter mutated producer hint: %q", source.Hint)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandAuthLogin: surface.CommandConcealed,
-	})
-	concealed := newRootErrorPresenter(
-		&cmdutil.Factory{ResolvedIdentity: core.AsUser},
-		recovery.NewProjector(func() *surface.Plan { return plan }),
-	).Present(source)
-	concealedProblem, _ := errs.ProblemOf(concealed)
-	if strings.Contains(concealedProblem.Hint, "auth login") ||
-		!strings.Contains(concealedProblem.Hint, "supported authorization flow") {
-		t.Fatalf("concealed recovery = %q, want target-free fallback", concealedProblem.Hint)
-	}
-}
-
-func TestRootErrorPresenterDoesNotRecommendUserLoginForBotPermission(t *testing.T) {
-	source := errs.NewPermissionError(errs.SubtypeMissingScope, "missing scope").
-		WithMissingScopes("drive:file:download").
-		WithIdentity("bot")
-
-	rendered := newRootErrorPresenter(
-		&cmdutil.Factory{ResolvedIdentity: core.AsBot},
-		recovery.NewProjector(nil),
-	).Present(source)
-	problem, _ := errs.ProblemOf(rendered)
-	if strings.Contains(problem.Hint, "auth login") ||
-		!strings.Contains(problem.Hint, "app developer") {
-		t.Fatalf("bot recovery = %q", problem.Hint)
-	}
-}
-
-func TestRootErrorPresenterDoesNotMutateNestedPermissionCause(t *testing.T) {
-	inner := errs.NewPermissionError(errs.SubtypeMissingScope, "inner permission").
-		WithMissingScopes("docx:document").
-		WithIdentity("user")
-	outer := errs.NewInternalError(errs.SubtypeUnknown, "outer failure").
-		WithHint("retry the operation").
-		WithCause(inner)
-
-	rendered := newRootErrorPresenter(
-		&cmdutil.Factory{ResolvedIdentity: core.AsUser},
-		recovery.NewProjector(nil),
-	).Present(outer)
-
-	if inner.Hint != "" {
-		t.Fatalf("presenter mutated nested producer hint: %q", inner.Hint)
-	}
-	problem, _ := errs.ProblemOf(rendered)
-	if got, want := problem.Hint, "retry the operation"; got != want {
-		t.Fatalf("rendered outer hint = %q, want %q", got, want)
-	}
-}
-
-func TestRootErrorPresenterDoesNotMutateNestedAuthenticationCause(t *testing.T) {
-	f := factoryWithDeclaredServiceScope(t)
-	source := internalauth.NewNeedUserAuthorizationError("ou_nested")
-	var inner *errs.AuthenticationError
-	if !errors.As(source, &inner) {
-		t.Fatalf("source = %T, want nested *errs.AuthenticationError", source)
-	}
-	originalHint := inner.Hint
-	outer := errs.NewInternalError(errs.SubtypeUnknown, "outer failure").
-		WithHint("retry the operation").
-		WithCause(source)
-
-	rendered := newRootErrorPresenter(f, recovery.NewProjector(nil)).Present(outer)
-
-	if got := inner.Hint; got != originalHint {
-		t.Fatalf("presenter mutated nested authentication hint: got %q want %q", got, originalHint)
-	}
-	problem, _ := errs.ProblemOf(rendered)
-	if got, want := problem.Hint, "retry the operation"; got != want {
-		t.Fatalf("rendered outer hint = %q, want %q", got, want)
-	}
-}
-
-func factoryWithDeclaredServiceScope(t *testing.T) *cmdutil.Factory {
-	t.Helper()
-	f := &cmdutil.Factory{ResolvedIdentity: core.AsUser}
-	var target registry.CommandEntry
-	for _, entry := range registry.CollectCommandScopes([]string{"calendar"}, "user") {
-		if len(entry.Scopes) > 0 {
-			target = entry
-			break
-		}
-	}
-	if target.Command == "" {
-		t.Fatal("failed to locate a service command with declared user scopes")
-	}
-	parts := strings.Split(target.Command, " ")
-	if len(parts) != 2 {
-		t.Fatalf("service command = %q, want resource and method", target.Command)
-	}
-	root := &cobra.Command{Use: "lark-cli"}
-	domain := &cobra.Command{Use: "calendar"}
-	resource := &cobra.Command{Use: parts[0]}
-	method := &cobra.Command{Use: parts[1]}
-	root.AddCommand(domain)
-	domain.AddCommand(resource)
-	resource.AddCommand(method)
-	f.CurrentCommand = method
-	return f
-}

cmd/event/consume.go

@@ -278,24 +278,27 @@ func preflightScopes(ctx context.Context, pf *preflightCtx) error {
 	if len(missing) == 0 {
 		return nil
 	}
-	permissionErr := errs.NewPermissionError(errs.SubtypeMissingScope,
+	return errs.NewPermissionError(errs.SubtypeMissingScope,
 		"missing required scopes for EventKey %s (as %s): %s",
 		pf.eventKey, pf.identity, strings.Join(missing, ", ")).
 		WithIdentity(string(pf.identity)).
-		WithMissingScopes(missing...)
-	if pf.identity.IsBot() {
-		permissionErr.WithHint("%s", botScopeRemediationHint(pf.brand, pf.appID, missing))
-	}
-	return permissionErr
+		WithMissingScopes(missing...).
+		WithHint("%s", scopeRemediationHint(pf.brand, pf.appID, pf.identity, missing))
 }
 
 // scopeRemediationHint returns an identity-appropriate fix for missing scopes.
-// The bot-specific scan-to-enable link adds the scopes to the app manifest,
-// after which the tenant token carries them. User recovery is generated from
-// the PermissionError's identity and missing_scopes by the root presenter.
-func botScopeRemediationHint(brand core.LarkBrand, appID string, missing []string) string {
-	return fmt.Sprintf("grant these scopes by scanning: %s",
-		addonsHintURL(brand, appID, missingScopeAddons(core.AsBot, missing)))
+// Bot: the scan-to-enable link adds the scopes to the app manifest, after which
+// the tenant token carries them. User: the scan link only updates the app
+// manifest — the user's own token still lacks the scopes until it is
+// re-authorized — so direct the user to re-login instead.
+func scopeRemediationHint(brand core.LarkBrand, appID string, identity core.Identity, missing []string) string {
+	if identity.IsBot() {
+		return fmt.Sprintf("grant these scopes by scanning: %s",
+			addonsHintURL(brand, appID, missingScopeAddons(identity, missing)))
+	}
+	return fmt.Sprintf(
+		"run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.",
+		strings.Join(missing, " "))
 }
 
 // preflightEventTypes verifies every RequiredConsoleEvents entry is subscribed
@@ -376,7 +379,7 @@ func resolveTenantToken(ctx context.Context, f *cmdutil.Factory, appID string) (
 	if result == nil || result.Token == "" {
 		return "", errs.NewAuthenticationError(errs.SubtypeTokenMissing,
 			"no tenant access token available for app %s", appID).
-			WithHint("check that app_secret is configured for this distribution")
+			WithHint("Check that app_secret is configured (lark-cli config show) and try 'lark-cli auth login'.")
 	}
 	return result.Token, nil
 }

cmd/event/event.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 func NewCmdEvents(f *cmdutil.Factory) *cobra.Command {
@@ -16,14 +17,31 @@ func NewCmdEvents(f *cmdutil.Factory) *cobra.Command {
 		Long:  `Unified event consumption system. Use 'event consume <EventKey>' to start consuming events.`,
 		// Without SilenceUsage, RunE errors print the full flag help banner.
 		SilenceUsage: true,
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cmd.SilenceUsage = true
+			// This hook shadows root's PersistentPreRun, so preserve the matched
+			// command for structured error and declared-scope hints.
+			f.CurrentCommand = cmd
+			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
+		},
 	}
+	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityRealtimeEvents)
 
-	cmd.AddCommand(NewCmdConsume(f))
-	cmd.AddCommand(NewCmdList(f))
-	cmd.AddCommand(NewCmdSchema(f))
-	cmd.AddCommand(NewCmdStatus(f))
-	cmd.AddCommand(NewCmdStop(f))
-	cmd.AddCommand(NewCmdBus(f))
+	consume := NewCmdConsume(f)
+	bus := NewCmdBus(f)
+	list := NewCmdList(f)
+	schema := NewCmdSchema(f)
+	status := NewCmdStatus(f)
+	stop := NewCmdStop(f)
+	for _, local := range []*cobra.Command{list, schema, status, stop} {
+		cmdutil.SetRuntimeCapabilities(local)
+	}
+	cmd.AddCommand(consume)
+	cmd.AddCommand(list)
+	cmd.AddCommand(schema)
+	cmd.AddCommand(status)
+	cmd.AddCommand(stop)
+	cmd.AddCommand(bus)
 
 	return cmd
 }

cmd/event/external_credential_guard_test.go

@@ -0,0 +1,146 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package event
+
+import (
+	"errors"
+	"io/fs"
+	"path/filepath"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/runtimeplan"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+func TestEventCommandsRejectDeniedRuntimeCapability(t *testing.T) {
+	cfg := &core.CliConfig{
+		AppID:     "cli_runtime_event_test",
+		AppSecret: "must-not-be-used",
+		Brand:     core.BrandFeishu,
+	}
+	denied := errs.NewValidationError(errs.SubtypeFailedPrecondition,
+		"real-time events are unavailable in this runtime").
+		WithHint("use a runtime that supports real-time events")
+	plan := runtimeplan.New(runtimeplan.Options{
+		Capabilities: func(capability runtimeplan.Capability) error {
+			if capability == runtimeplan.CapabilityRealtimeEvents {
+				return denied
+			}
+			return nil
+		},
+	})
+
+	t.Run("consume", func(t *testing.T) {
+		f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, cfg, plan)
+		cmd := NewCmdEvents(f)
+		args := []string{"consume", "guarded-before-event-lookup"}
+		matched, _, err := cmd.Find(args)
+		if err != nil {
+			t.Fatalf("Find() error = %v", err)
+		}
+		cmd.SetArgs(args)
+		requireExternalEventGuard(t, cmd.Execute())
+		if f.CurrentCommand != matched {
+			t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
+		}
+	})
+
+	t.Run("bus", func(t *testing.T) {
+		configDir := t.TempDir()
+		t.Setenv("LARKSUITE_CLI_CONFIG_DIR", configDir)
+		f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, cfg, plan)
+		cmd := NewCmdEvents(f)
+		args := []string{"_bus"}
+		matched, _, err := cmd.Find(args)
+		if err != nil {
+			t.Fatalf("Find() error = %v", err)
+		}
+		cmd.SetArgs(args)
+		requireExternalEventGuard(t, cmd.Execute())
+		if f.CurrentCommand != matched {
+			t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
+		}
+		if _, err := vfs.Stat(filepath.Join(configDir, "events")); !errors.Is(err, fs.ErrNotExist) {
+			t.Fatalf("event bus created runtime files before guard: %v", err)
+		}
+	})
+}
+
+func TestEventCommandRuntimeCapabilityMatrix(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdEvents(f)
+
+	parentCapabilities := cmdutil.GetRuntimeCapabilities(cmd)
+	if len(parentCapabilities) != 1 || parentCapabilities[0] != runtimeplan.CapabilityRealtimeEvents {
+		t.Fatalf("event capabilities = %v, want [%s]", parentCapabilities, runtimeplan.CapabilityRealtimeEvents)
+	}
+
+	wantRealtime := map[string]bool{
+		"_bus":    true,
+		"consume": true,
+		"list":    false,
+		"schema":  false,
+		"status":  false,
+		"stop":    false,
+	}
+	children := make(map[string]*cobra.Command, len(wantRealtime))
+	for _, child := range cmd.Commands() {
+		name := child.Name()
+		want, ok := wantRealtime[name]
+		if !ok {
+			t.Fatalf("event command %q is missing from the runtime capability matrix", name)
+		}
+		children[name] = child
+		got := cmdutil.GetRuntimeCapabilities(child)
+		if want {
+			if len(got) != 1 || got[0] != runtimeplan.CapabilityRealtimeEvents {
+				t.Errorf("event %s capabilities = %v, want [%s]", name, got, runtimeplan.CapabilityRealtimeEvents)
+			}
+			continue
+		}
+		if len(got) != 0 {
+			t.Errorf("event %s capabilities = %v, want source-neutral local command", name, got)
+		}
+	}
+	if len(children) != len(wantRealtime) {
+		t.Fatalf("event command matrix covered %d commands, want %d", len(children), len(wantRealtime))
+	}
+
+	// Clearing the parent declaration must also clear both consumers. This
+	// proves they inherit the fail-closed default instead of duplicating a
+	// leaf annotation that future event commands could forget.
+	cmdutil.SetRuntimeCapabilities(cmd)
+	for _, name := range []string{"consume", "_bus"} {
+		if got := cmdutil.GetRuntimeCapabilities(children[name]); len(got) != 0 {
+			t.Errorf("event %s capabilities after clearing parent = %v, want inherited empty declaration", name, got)
+		}
+	}
+}
+
+func requireExternalEventGuard(t *testing.T, err error) {
+	t.Helper()
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("error = %T %v, want typed problem", err, err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("problem = %s/%s, want %s/%s",
+			problem.Category, problem.Subtype, errs.CategoryValidation, errs.SubtypeFailedPrecondition)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("error = %T, want *errs.ValidationError", err)
+	}
+	if validationErr.Param != "" {
+		t.Fatalf("param = %q, want empty", validationErr.Param)
+	}
+	if problem.Hint == "" {
+		t.Fatal("hint is empty")
+	}
+}

cmd/event/preflight_test.go

@@ -264,9 +264,18 @@ func TestPreflightEventTypes_CallbackAllSubscribed_Passes(t *testing.T) {
 	}
 }
 
-func TestBotScopeRemediationHintUsesScanLink(t *testing.T) {
-	bot := botScopeRemediationHint(core.BrandFeishu, "cli_x", []string{"im:message"})
+func TestScopeRemediationHint_ByIdentity(t *testing.T) {
+	// bot: scan-to-enable link (adds scopes to app manifest)
+	bot := scopeRemediationHint(core.BrandFeishu, "cli_x", core.AsBot, []string{"im:message"})
 	if !strings.Contains(bot, "/page/launcher?clientID=cli_x&addons=") {
 		t.Errorf("bot hint should give the scan link, got: %s", bot)
 	}
+	// user: re-login (scan link cannot grant scopes to the user's own token)
+	user := scopeRemediationHint(core.BrandFeishu, "cli_x", core.AsUser, []string{"im:message"})
+	if !strings.Contains(user, "auth login --scope") {
+		t.Errorf("user hint should direct to auth login, got: %s", user)
+	}
+	if strings.Contains(user, "/page/launcher") {
+		t.Errorf("user hint must NOT use the scan link, got: %s", user)
+	}
 }

cmd/flag_gate.go

@@ -1,67 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"errors"
-
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-
-	"github.com/larksuite/cli/internal/surface"
-)
-
-// globalFlagTargets maps each root persistent flag to the command capability
-// it belongs to. A new domain-tied global flag must add a row.
-var globalFlagTargets = map[string]surface.CommandID{
-	"profile": surface.CommandProfile,
-}
-
-// flagGateAnnotation distinguishes a surface-retired flag from one hidden
-// cosmetically (single-app mode force-shows the latter in root help).
-const flagGateAnnotation = "lark:surface_concealed_flag"
-
-// applyPluginFlagGate hides and rejects global flags whose exact command
-// capability is absent from this build. It is called only by the explicit
-// distribution presentation pass.
-func applyPluginFlagGate(root *cobra.Command, plan *surface.Plan) {
-	for flagName, target := range globalFlagTargets {
-		if plan.CanReference(target) {
-			continue
-		}
-		fl := root.PersistentFlags().Lookup(flagName)
-		if fl == nil {
-			continue
-		}
-		fl.Hidden = true
-		if fl.Annotations == nil {
-			fl.Annotations = map[string][]string{}
-		}
-		fl.Annotations[flagGateAnnotation] = []string{"true"}
-		fl.Value = &gatedFlagValue{name: flagName, inner: fl.Value}
-	}
-}
-
-func isPolicyGatedFlag(fl *pflag.Flag) bool {
-	return fl != nil && fl.Annotations[flagGateAnnotation] != nil
-}
-
-// gatedFlagValue rejects at parse time, before cobra's help/version fast
-// paths (which never reach PersistentPreRunE). Its Set error carries
-// cobra's own unknown-flag wording so the root FlagErrorFunc classifies it
-// as an ordinary unknown flag without exposing policy state. Cobra may add
-// different parse context on root/group paths than on leaf commands.
-type gatedFlagValue struct {
-	name  string
-	inner pflag.Value
-}
-
-func (g *gatedFlagValue) String() string { return g.inner.String() }
-func (g *gatedFlagValue) Type() string   { return g.inner.Type() }
-func (g *gatedFlagValue) Set(string) error {
-	// Intermediate parse error, not a final envelope: pflag wraps it and
-	// the root FlagErrorFunc (flagDidYouMean) converts it to the typed
-	// unknown-flag validation error.
-	return errors.New("unknown flag: --" + g.name) //nolint:forbidigo // intermediate parse error; flagDidYouMean emits the typed envelope
-}

cmd/notice_test.go

@@ -23,7 +23,7 @@ func TestComposePendingNoticeDeprecatedCommand(t *testing.T) {
 		Skill:       "lark-sheets",
 	})
 
-	got := composePendingNotice(nil)
+	got := composePendingNotice()
 	if got == nil {
 		t.Fatal("composePendingNotice() = nil, want deprecated_command entry")
 	}
@@ -51,7 +51,7 @@ func TestComposePendingNoticeEmpty(t *testing.T) {
 	t.Cleanup(func() { deprecation.SetPending(nil) })
 	deprecation.SetPending(nil)
 
-	if got := composePendingNotice(nil); got != nil {
+	if got := composePendingNotice(); got != nil {
 		// update/skills pending are process-global; only assert the absence of
 		// our own key to stay robust against unrelated pending state.
 		if _, ok := got["deprecated_command"]; ok {

cmd/platform_bootstrap.go

@@ -35,10 +35,7 @@ const userPolicyFileName = "policy.yml"
 //
 // pluginRules carries Plugin.Restrict() contributions collected from
 // the InstallAll phase; nil/empty is fine.
-//
-// The returned denied map (nil when no rule denied anything) feeds the
-// optional, build-local distribution presentation pass in build.go.
-func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) (map[string]cmdpolicy.Denial, error) {
+func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.PluginRule) error {
 	// Plugin rules shadow the yaml source entirely (Resolve: plugin >
 	// yaml). When a plugin contributed rules we therefore do NOT even
 	// read ~/.lark-cli/policy.yml: build.go fail-CLOSES on any policy
@@ -68,7 +65,7 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 			// show` reports "no policy" instead of a stale rule that
 			// doesn't reflect the current command tree.
 			cmdpolicy.SetActive(nil)
-			return nil, lerr
+			return lerr
 		}
 		yamlRules = loaded
 	}
@@ -80,11 +77,11 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 	})
 	if err != nil {
 		cmdpolicy.SetActive(nil)
-		return nil, err
+		return err
 	}
 	if len(rules) == 0 {
 		cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{Source: source})
-		return nil, nil
+		return nil
 	}
 
 	// RuleName attributes a denial to a specific rule in the envelope.
@@ -103,12 +100,11 @@ func applyUserPolicyPruning(rootCmd *cobra.Command, pluginRules []cmdpolicy.Plug
 	cmdpolicy.Apply(rootCmd, denied)
 
 	cmdpolicy.SetActive(&cmdpolicy.ActivePolicy{
-		Rules:        rules,
-		Source:       source,
-		DeniedByPath: denied,
+		Rules:       rules,
+		Source:      source,
+		DeniedPaths: len(denied),
 	})
-
-	return denied, nil
+	return nil
 }
 
 // installPluginsAndHooks runs the InstallAll phase on the globally-
@@ -160,22 +156,7 @@ func recordInventory(installResult *internalplatform.InstallResult) {
 			AllowUnannotated: r.Rule.AllowUnannotated,
 		})
 	}
-	skillSrcs := make([]internalplatform.SkillsInventorySource, 0, len(installResult.PluginSkills))
-	for _, ps := range installResult.PluginSkills {
-		if ps.SkillsOverlay == nil {
-			continue
-		}
-		skillSrcs = append(skillSrcs, internalplatform.SkillsInventorySource{
-			PluginName: ps.PluginName,
-			View: internalplatform.SkillsOverlayView{
-				Allow:   ps.SkillsOverlay.Allow,
-				Remove:  ps.SkillsOverlay.Remove,
-				Overlay: ps.SkillsOverlay.Overlay != nil,
-				Base:    ps.SkillsOverlay.Base != nil,
-			},
-		})
-	}
-	internalplatform.SetActiveInventory(internalplatform.BuildInventory(pluginSrcs, installResult.Registry, ruleSrcs, skillSrcs))
+	internalplatform.SetActiveInventory(internalplatform.BuildInventory(pluginSrcs, installResult.Registry, ruleSrcs))
 }
 
 // wireHooks installs Observer/Wrapper hooks onto every runnable command
@@ -186,20 +167,7 @@ func wireHooks(ctx context.Context, rootCmd *cobra.Command, reg *hook.Registry)
 	if reg == nil {
 		return nil
 	}
-	installHooks(rootCmd, reg)
-	return emitStartup(ctx, reg)
-}
-
-func installHooks(rootCmd *cobra.Command, reg *hook.Registry) {
-	if reg != nil {
-		hook.Install(rootCmd, reg, cobraCommandViewSource{})
-	}
-}
-
-func emitStartup(ctx context.Context, reg *hook.Registry) error {
-	if reg == nil {
-		return nil
-	}
+	hook.Install(rootCmd, reg, cobraCommandViewSource{})
 	return hook.Emit(ctx, reg, platform.Startup, nil)
 }
 

cmd/platform_bootstrap_test.go

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

cmd/platform_guards.go

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

cmd/presentation.go

@@ -1,326 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"strings"
-
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-
-	configcmd "github.com/larksuite/cli/cmd/config"
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/surface"
-)
-
-const annotationUnavailableMessage = "lark:presentation_unavailable_message"
-
-type projectedCommand struct {
-	state  surface.CommandState
-	denial cmdpolicy.Denial
-}
-
-// presentationProjection keeps one distribution's build-time presentation
-// state and denial provenance together, so a concealed command retains the
-// cause installed on its unavailable projection.
-type presentationProjection struct {
-	commands map[surface.CommandID]projectedCommand
-}
-
-func newPresentationProjection(denied map[string]cmdpolicy.Denial) *presentationProjection {
-	projection := &presentationProjection{
-		commands: make(map[surface.CommandID]projectedCommand, len(denied)),
-	}
-	for path, denial := range denied {
-		projection.commands[surface.CommandID(path)] = projectedCommand{
-			state:  surface.CommandDeniedVisible,
-			denial: denial,
-		}
-	}
-	return projection
-}
-
-func (p *presentationProjection) recordConcealed(path string, denial cmdpolicy.Denial) {
-	p.commands[surface.CommandID(path)] = projectedCommand{
-		state:  surface.CommandConcealed,
-		denial: denial,
-	}
-}
-
-func (p *presentationProjection) denial(path string) (cmdpolicy.Denial, bool) {
-	command, ok := p.commands[surface.CommandID(path)]
-	if !ok || command.state != surface.CommandConcealed {
-		return cmdpolicy.Denial{}, false
-	}
-	return command.denial, true
-}
-
-func (p *presentationProjection) plan() *surface.Plan {
-	states := make(map[surface.CommandID]surface.CommandState, len(p.commands))
-	for id, command := range p.commands {
-		states[id] = command.state
-	}
-	return surface.NewPlan(states)
-}
-
-func (p *presentationProjection) hasConcealedCommands() bool {
-	for _, command := range p.commands {
-		if command.state == surface.CommandConcealed {
-			return true
-		}
-	}
-	return false
-}
-
-// applyDistributionPresentation projects enforcement decisions onto the
-// command surface of this one build. Enforcement has already installed its
-// policy-rich deny stubs. Without an explicit presentation option, those stubs
-// and their legacy help/completion behavior are left untouched.
-func applyDistributionPresentation(
-	root *cobra.Command,
-	cfg restrictionPresentationConfig,
-	denied map[string]cmdpolicy.Denial,
-) (*surface.Plan, bool) {
-	projection := newPresentationProjection(denied)
-	if !cfg.enabled {
-		return projection.plan(), false
-	}
-
-	collectPluginConcealments(root, denied, projection)
-	if cfg.hidePolicyDiagnostics {
-		collectDiagnosticConcealments(root, projection)
-	}
-	propagateConcealedPureGroups(root, projection)
-
-	installUnavailableProjections(root, projection, cfg.effectiveUnavailableMessage())
-
-	plan := projection.plan()
-	applyPresentationAffordances(root, plan)
-	return plan, projection.hasConcealedCommands()
-}
-
-func collectPluginConcealments(
-	root *cobra.Command,
-	denied map[string]cmdpolicy.Denial,
-	projection *presentationProjection,
-) {
-	for path, denial := range denied {
-		if !cmdpolicy.IsPluginPolicySource(denial.PolicySource) {
-			continue
-		}
-		cmd := findByPath(root, path)
-		if cmd == nil || commandDenialLayer(cmd) == cmdpolicy.LayerStrictMode {
-			continue
-		}
-		projection.recordConcealed(path, denial)
-	}
-}
-
-func collectDiagnosticConcealments(
-	root *cobra.Command,
-	projection *presentationProjection,
-) {
-	for _, path := range cmdpolicy.DiagnosticPaths() {
-		if findByPath(root, path) == nil {
-			continue
-		}
-		projection.recordConcealed(path, cmdpolicy.Denial{
-			Layer:        cmdpolicy.LayerPolicy,
-			PolicySource: "distribution:presentation",
-			ReasonCode:   "diagnostics_concealed",
-			Reason:       "policy diagnostics concealed by the distribution",
-		})
-	}
-}
-
-func propagateConcealedPureGroups(
-	root *cobra.Command,
-	projection *presentationProjection,
-) {
-	// A pure parent becomes absent only when every live child is absent. Repeat
-	// bottom-up until all newly-empty intermediate groups converge.
-	for {
-		changed := false
-		plan := projection.plan()
-		walkCommandsPostOrder(root, func(cmd *cobra.Command) {
-			path, denial, ok := concealedPureGroup(cmd, plan, projection)
-			if !ok {
-				return
-			}
-			projection.recordConcealed(path, denial)
-			changed = true
-		})
-		if !changed {
-			break
-		}
-	}
-}
-
-func concealedPureGroup(
-	cmd *cobra.Command,
-	plan *surface.Plan,
-	projection *presentationProjection,
-) (string, cmdpolicy.Denial, bool) {
-	path := cmdpolicy.CanonicalPath(cmd)
-	if !cmd.HasParent() || !isPresentationPureGroup(cmd) ||
-		plan.IsConcealed(surface.CommandID(path)) {
-		return "", cmdpolicy.Denial{}, false
-	}
-	children := cmd.Commands()
-	if len(children) == 0 {
-		return "", cmdpolicy.Denial{}, false
-	}
-
-	var cause cmdpolicy.Denial
-	for _, child := range children {
-		childPath := cmdpolicy.CanonicalPath(child)
-		if !plan.IsConcealed(surface.CommandID(childPath)) {
-			return "", cmdpolicy.Denial{}, false
-		}
-		if denial, ok := projection.denial(childPath); ok && cause.Layer == "" {
-			cause = denial
-		}
-	}
-	if cause.Layer == "" {
-		cause = cmdpolicy.Denial{
-			Layer:        cmdpolicy.LayerPolicy,
-			PolicySource: "distribution:presentation",
-			ReasonCode:   "all_children_concealed",
-			Reason:       "all child commands are concealed",
-		}
-	}
-	return path, cause, true
-}
-
-func installUnavailableProjections(
-	root *cobra.Command,
-	projection *presentationProjection,
-	message string,
-) {
-	for id, command := range projection.commands {
-		if command.state != surface.CommandConcealed {
-			continue
-		}
-		path := string(id)
-		if cmd := findByPath(root, path); cmd != nil {
-			installUnavailableProjection(cmd, path, command.denial, message)
-		}
-	}
-}
-
-func applyPresentationAffordances(root *cobra.Command, plan *surface.Plan) {
-	applyPluginFlagGate(root, plan)
-	configcmd.ProjectInitHelp(
-		findByPath(root, string(surface.CommandConfigInit)),
-		plan.CanReference(surface.CommandConfigBind),
-	)
-	root.Long = renderRootHelpSections(rootLongSections, plan)
-	root.SetUsageTemplate(renderRootUsageTemplate(plan))
-}
-
-func commandDenialLayer(cmd *cobra.Command) string {
-	if cmd == nil || cmd.Annotations == nil {
-		return ""
-	}
-	return cmd.Annotations[cmdpolicy.AnnotationDenialLayer]
-}
-
-func isPresentationPureGroup(cmd *cobra.Command) bool {
-	if cmd == nil {
-		return false
-	}
-	return (cmd.Run == nil && cmd.RunE == nil) || cmdpolicy.IsPureGroup(cmd)
-}
-
-func walkCommandsPostOrder(cmd *cobra.Command, visit func(*cobra.Command)) {
-	for _, child := range cmd.Commands() {
-		walkCommandsPostOrder(child, visit)
-	}
-	visit(cmd)
-}
-
-// installUnavailableProjection changes presentation only. It preserves the
-// enforcement denial as the in-process cause when one exists, while the wire
-// intentionally exposes no policy source, rule name, or reason code.
-func installUnavailableProjection(cmd *cobra.Command, path string, denial cmdpolicy.Denial, message string) {
-	cmd.Hidden = true
-	cmd.DisableFlagParsing = true
-	cmd.Args = cobra.ArbitraryArgs
-	cmd.PersistentPreRunE = func(c *cobra.Command, _ []string) error {
-		c.SilenceUsage = true
-		return nil
-	}
-	cmd.PersistentPreRun = nil
-	cmd.PreRunE = nil
-	cmd.PreRun = nil
-
-	hideFlags := func(flags *pflag.FlagSet) {
-		flags.VisitAll(func(flag *pflag.Flag) {
-			flag.Hidden = true
-		})
-	}
-	// Hide only flags owned by this command. cmd.Flags() may contain inherited
-	// flag pointers after Cobra merges sets; mutating those would hide a global
-	// flag from unrelated commands.
-	hideFlags(cmd.LocalNonPersistentFlags())
-	hideFlags(cmd.PersistentFlags())
-	cmd.ValidArgs = nil
-	cmd.ValidArgsFunction = func(*cobra.Command, []string, string) ([]string, cobra.ShellCompDirective) {
-		return nil, cobra.ShellCompDirectiveNoFileComp
-	}
-
-	if cmd.Annotations == nil {
-		cmd.Annotations = map[string]string{}
-	}
-	cmd.Annotations[annotationUnavailableMessage] = message
-	if cmd.Annotations[cmdpolicy.AnnotationDenialLayer] == "" {
-		cmd.Annotations[cmdpolicy.AnnotationDenialLayer] = denial.Layer
-		cmd.Annotations[cmdpolicy.AnnotationDenialSource] = denial.PolicySource
-	}
-
-	cmd.RunE = func(*cobra.Command, []string) error {
-		err := errs.NewValidationError(errs.SubtypeCommandUnavailable, "%s", message)
-		if denial.Layer != "" {
-			err.WithCause(cmdpolicy.CommandDeniedFromDenial(path, denial))
-		}
-		return err
-	}
-	cmd.Run = nil
-}
-
-// unavailableHelpMessage is deliberately keyed only by the opt-in projection
-// annotation. A legacy Restrict denial carries enforcement annotations but
-// continues to use Cobra's stock explicit-help behavior.
-func unavailableHelpMessage(cmd *cobra.Command) (string, bool) {
-	for current := cmd; current != nil; current = current.Parent() {
-		if current.Annotations == nil {
-			continue
-		}
-		if message := current.Annotations[annotationUnavailableMessage]; message != "" {
-			return message, true
-		}
-	}
-	return "", false
-}
-
-// findByPath resolves a canonical slash path (for example
-// "config/policy/show") to a command node.
-func findByPath(root *cobra.Command, path string) *cobra.Command {
-	cur := root
-	for _, segment := range strings.Split(path, "/") {
-		var next *cobra.Command
-		for _, child := range cur.Commands() {
-			if child.Name() == segment {
-				next = child
-				break
-			}
-		}
-		if next == nil {
-			return nil
-		}
-		cur = next
-	}
-	return cur
-}

cmd/presentation_options.go

@@ -1,72 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-// defaultRestrictedCommandUnavailableMessage is the distribution-neutral
-// fallback for a concealed command. It lives in the presentation layer rather
-// than extension/platform.Rule: the same enforcement rule may be rendered as a
-// visible policy denial by one host and as an absent capability by another.
-const defaultRestrictedCommandUnavailableMessage = "command not included in this build"
-
-// restrictionPresentationConfig is a per-Build snapshot. It is deliberately
-// private so adding a future presentation knob cannot break downstream
-// unkeyed struct literals.
-type restrictionPresentationConfig struct {
-	enabled               bool
-	unavailableMessage    string
-	hidePolicyDiagnostics bool
-}
-
-func (c restrictionPresentationConfig) effectiveUnavailableMessage() string {
-	if c.unavailableMessage != "" {
-		return c.unavailableMessage
-	}
-	return defaultRestrictedCommandUnavailableMessage
-}
-
-// RestrictionPresentationOption configures the presentation of commands
-// denied by an embedded distribution's Restrict plugin.
-//
-// Values are accepted only by ConcealRestrictedCommands. The pointed-to
-// configuration type is private by design; callers use the constructors in
-// this file instead of depending on a public struct layout.
-type RestrictionPresentationOption func(*restrictionPresentationConfig)
-
-// ConcealRestrictedCommands opts one command tree into presenting
-// plugin-restricted commands as capabilities absent from the distribution.
-//
-// Restrict remains the enforcement boundary. Without this BuildOption,
-// existing Restrict plugins keep their established failed_precondition
-// envelope, explicit-help, and completion behavior.
-//
-// Pass the returned option to Build, or to ExecuteWithOptions when using the
-// standard host entrypoint.
-func ConcealRestrictedCommands(opts ...RestrictionPresentationOption) BuildOption {
-	presentation := restrictionPresentationConfig{enabled: true}
-	for _, opt := range opts {
-		if opt != nil {
-			opt(&presentation)
-		}
-	}
-	return func(cfg *buildConfig) {
-		cfg.presentation = presentation
-	}
-}
-
-// UnavailableMessage customizes the error message for a concealed command.
-// An empty message selects the distribution-neutral default.
-func UnavailableMessage(message string) RestrictionPresentationOption {
-	return func(cfg *restrictionPresentationConfig) {
-		cfg.unavailableMessage = message
-	}
-}
-
-// HidePolicyDiagnostics removes the policy self-inspection commands from a
-// concealed distribution. Without it, those commands remain the operator's
-// recovery and inspection escape hatch.
-func HidePolicyDiagnostics() RestrictionPresentationOption {
-	return func(cfg *restrictionPresentationConfig) {
-		cfg.hidePolicyDiagnostics = true
-	}
-}

cmd/presentation_options_test.go

@@ -1,73 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import "testing"
-
-// Preserve callers that store the original entrypoint as a function value.
-// Making Execute variadic would compile at ordinary call sites but break this
-// established source contract.
-var _ func() int = Execute
-
-func TestConcealRestrictedCommandsDefaults(t *testing.T) {
-	cfg := &buildConfig{}
-	ConcealRestrictedCommands()(cfg)
-
-	if !cfg.presentation.enabled {
-		t.Fatal("concealment must be explicitly enabled by the BuildOption")
-	}
-	if cfg.presentation.hidePolicyDiagnostics {
-		t.Fatal("policy diagnostics must remain available by default")
-	}
-	if got := cfg.presentation.effectiveUnavailableMessage(); got != defaultRestrictedCommandUnavailableMessage {
-		t.Errorf("message = %q, want %q", got, defaultRestrictedCommandUnavailableMessage)
-	}
-}
-
-func TestConcealRestrictedCommandsOptions(t *testing.T) {
-	cfg := &buildConfig{}
-	ConcealRestrictedCommands(
-		UnavailableMessage("not part of acme-cli"),
-		HidePolicyDiagnostics(),
-	)(cfg)
-
-	if !cfg.presentation.enabled {
-		t.Fatal("concealment must be enabled")
-	}
-	if !cfg.presentation.hidePolicyDiagnostics {
-		t.Fatal("HidePolicyDiagnostics option was not applied")
-	}
-	if got := cfg.presentation.effectiveUnavailableMessage(); got != "not part of acme-cli" {
-		t.Errorf("message = %q, want custom message", got)
-	}
-}
-
-func TestConcealRestrictedCommandsIsBuildLocal(t *testing.T) {
-	concealed := &buildConfig{}
-	ordinary := &buildConfig{}
-
-	ConcealRestrictedCommands(
-		UnavailableMessage("acme only"),
-		HidePolicyDiagnostics(),
-	)(concealed)
-
-	if ordinary.presentation.enabled {
-		t.Fatal("applying an option to one build must not enable another")
-	}
-	if ordinary.presentation.hidePolicyDiagnostics {
-		t.Fatal("applying an option to one build must not mutate another")
-	}
-	if got := ordinary.presentation.effectiveUnavailableMessage(); got != defaultRestrictedCommandUnavailableMessage {
-		t.Errorf("ordinary message = %q, want default", got)
-	}
-}
-
-func TestUnavailableMessageEmptyUsesDefault(t *testing.T) {
-	cfg := &buildConfig{}
-	ConcealRestrictedCommands(UnavailableMessage(""))(cfg)
-
-	if got := cfg.presentation.effectiveUnavailableMessage(); got != defaultRestrictedCommandUnavailableMessage {
-		t.Errorf("message = %q, want %q", got, defaultRestrictedCommandUnavailableMessage)
-	}
-}

cmd/presentation_test.go

@@ -1,757 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"os"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/extension/platform"
-	"github.com/larksuite/cli/internal/cmdpolicy"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/deprecation"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/skillscheck"
-	"github.com/larksuite/cli/internal/surface"
-	"github.com/larksuite/cli/internal/update"
-)
-
-func registerRestriction(t *testing.T, deny []string, configure func(*platform.Builder) *platform.Builder) {
-	t.Helper()
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-	builder := platform.NewPlugin("acme", "1.0").
-		Restrict(&platform.Rule{Deny: deny})
-	if configure != nil {
-		builder = configure(builder)
-	}
-	platform.Register(builder.MustBuild())
-}
-
-func TestBuildInternalRestrictDefaultPreservesLegacyContract(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"skills/read"}, nil)
-
-	runtime, root, _ := buildInternal(context.Background(), buildInvocationForTest(t))
-	leaf := findByPath(root, "skills/read")
-	if leaf == nil {
-		t.Fatal("skills/read not found")
-	}
-	if got := runtime.surface.State(surface.CommandSkillsRead); got != surface.CommandDeniedVisible {
-		t.Fatalf("surface state = %v, want denied-visible", got)
-	}
-	if _, projected := unavailableHelpMessage(leaf); projected {
-		t.Fatal("legacy Restrict unexpectedly received concealment presentation")
-	}
-
-	err := leaf.RunE(leaf, nil)
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("RunE error = %T %v, want ValidationError", err, err)
-	}
-	if validation.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %q, want failed_precondition", validation.Subtype)
-	}
-	if !strings.Contains(validation.Hint, "source plugin:acme") ||
-		!strings.Contains(validation.Hint, "reason_code") {
-		t.Errorf("legacy policy metadata missing from hint: %q", validation.Hint)
-	}
-	if flag := leaf.Flags().Lookup("json"); flag == nil || flag.Hidden {
-		t.Errorf("legacy Restrict must preserve local flag presentation; flag=%+v", flag)
-	}
-
-	var help bytes.Buffer
-	root.SetOut(&help)
-	root.SetErr(&help)
-	if err := root.Help(); err != nil {
-		t.Fatal(err)
-	}
-	for _, title := range []string{"Lark domains:", "Agent tooling:", "CLI management:"} {
-		if !strings.Contains(help.String(), title) {
-			t.Errorf("default root help lost group %q", title)
-		}
-	}
-}
-
-func TestBuildInternalConcealmentIsExplicitAndKeepsDenialAsCause(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"skills/read"}, nil)
-
-	runtime, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(UnavailableMessage("not shipped by acme")),
-	)
-	leaf := findByPath(root, "skills/read")
-	if got := runtime.surface.State(surface.CommandSkillsRead); got != surface.CommandConcealed {
-		t.Fatalf("surface state = %v, want concealed", got)
-	}
-
-	err := leaf.RunE(leaf, nil)
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) {
-		t.Fatalf("RunE error = %T %v, want ValidationError", err, err)
-	}
-	if validation.Subtype != errs.SubtypeCommandUnavailable ||
-		validation.Message != "not shipped by acme" || validation.Hint != "" {
-		t.Errorf("concealed error = %+v", validation)
-	}
-	var denied *platform.CommandDeniedError
-	if !errors.As(err, &denied) || denied.Path != "skills/read" ||
-		denied.PolicySource != "plugin:acme" {
-		t.Errorf("enforcement cause not preserved: %T %+v", err, denied)
-	}
-
-	if flag := leaf.Flags().Lookup("json"); flag == nil || !flag.Hidden {
-		t.Errorf("concealed command must hide owned flags; flag=%+v", flag)
-	}
-	if flag := root.PersistentFlags().Lookup("profile"); flag == nil || flag.Hidden {
-		t.Errorf("concealing a leaf must not mutate inherited global flags; flag=%+v", flag)
-	}
-	if args, _ := leaf.ValidArgsFunction(leaf, nil, ""); len(args) != 0 {
-		t.Errorf("concealed command completed positionals: %v", args)
-	}
-
-	help := findByPath(root, "help")
-	if help == nil || help.RunE == nil {
-		t.Fatal("concealment-specific help command not installed")
-	}
-	err = help.RunE(help, []string{"skills", "read"})
-	if !errors.As(err, &validation) || validation.Subtype != errs.SubtypeCommandUnavailable {
-		t.Errorf("help on concealed command = %v, want command_unavailable", err)
-	}
-
-	active := cmdpolicy.GetActive()
-	if active == nil || active.DeniedByPath["skills/read"].PolicySource != "plugin:acme" {
-		t.Fatalf("presentation overwrote enforcement snapshot: %+v", active)
-	}
-}
-
-func TestDistributionPresentationNeverConcealsYAMLPolicy(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	leaf := &cobra.Command{Use: "probe", RunE: func(*cobra.Command, []string) error { return nil }}
-	root.AddCommand(leaf)
-	denial := cmdpolicy.Denial{
-		Layer:        cmdpolicy.LayerPolicy,
-		PolicySource: "yaml:/tmp/policy.yml",
-		ReasonCode:   "command_denylisted",
-		Reason:       "denied by user policy",
-	}
-	denied := map[string]cmdpolicy.Denial{"probe": denial}
-	cmdpolicy.Apply(root, denied)
-
-	plan, concealed := applyDistributionPresentation(
-		root,
-		restrictionPresentationConfig{enabled: true},
-		denied,
-	)
-	if concealed {
-		t.Fatal("user-owned YAML denial must not be projected as absent")
-	}
-	if got := plan.State("probe"); got != surface.CommandDeniedVisible {
-		t.Fatalf("surface state = %v, want denied-visible", got)
-	}
-	err := leaf.RunE(leaf, nil)
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) || validation.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("YAML denial changed by distribution presentation: %v", err)
-	}
-}
-
-func TestRootGroupsFollowSurfaceConcealmentNotLegacyHiddenState(t *testing.T) {
-	newRoot := func() *cobra.Command {
-		root := &cobra.Command{Use: "lark-cli"}
-		child := &cobra.Command{
-			Use:     "skills",
-			GroupID: groupTooling,
-			RunE:    func(*cobra.Command, []string) error { return nil },
-		}
-		root.AddCommand(child)
-		return root
-	}
-
-	yamlRoot := newRoot()
-	yamlChild := findByPath(yamlRoot, "skills")
-	yamlChild.Hidden = true
-	finalizeRootCommandGroups(yamlRoot, surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandSkills: surface.CommandDeniedVisible,
-	}))
-	if len(yamlRoot.Groups()) != 1 || yamlRoot.Groups()[0].ID != groupTooling {
-		t.Fatalf("legacy/YAML hidden command removed its group: %+v", yamlRoot.Groups())
-	}
-
-	concealedRoot := newRoot()
-	finalizeRootCommandGroups(concealedRoot, surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandSkills: surface.CommandConcealed,
-	}))
-	if len(concealedRoot.Groups()) != 0 {
-		t.Fatalf("concealed-only group remained visible: %+v", concealedRoot.Groups())
-	}
-	if got := findByPath(concealedRoot, "skills").GroupID; got != "" {
-		t.Fatalf("concealed child retained undefined GroupID %q", got)
-	}
-}
-
-func TestPresentationDropsRootSkillsFooterWithSkillsRead(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	root.SetUsageTemplate(rootUsageTemplate)
-	applyPresentationAffordances(root, surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandSkillsRead: surface.CommandConcealed,
-	}))
-	if strings.Contains(root.UsageTemplate(), "Skills setup (one-time, humans)") {
-		t.Fatalf("concealed skills/read left the root skills footer:\n%s", root.UsageTemplate())
-	}
-}
-
-func TestPresentationProjectsEveryFrameworkOwnedRootHelpTarget(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli", Long: rootLong}
-	root.SetUsageTemplate(rootUsageTemplate)
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		rootHelpAPI:            surface.CommandConcealed,
-		surface.CommandSchema:  surface.CommandConcealed,
-		rootHelpCalendarAgenda: surface.CommandConcealed,
-		rootHelpMailList:       surface.CommandConcealed,
-	})
-
-	applyPresentationAffordances(root, plan)
-
-	for _, dead := range []string{
-		"lark-cli api ",
-		"lark-cli schema ",
-		"lark-cli calendar +agenda",
-		"lark-cli mail user_mailbox.messages list",
-	} {
-		if strings.Contains(root.Long, dead) || strings.Contains(root.UsageTemplate(), dead) {
-			t.Errorf("concealed root-help target %q survived:\nLong:\n%s\nTemplate:\n%s",
-				dead, root.Long, root.UsageTemplate())
-		}
-	}
-	if !strings.Contains(root.Long, "Browse commands:") ||
-		!strings.Contains(root.UsageTemplate(), "lark-cli <command>") {
-		t.Fatalf("target-independent root guidance was removed:\nLong:\n%s\nTemplate:\n%s",
-			root.Long, root.UsageTemplate())
-	}
-}
-
-func TestFrameworkOwnedRootHelpTargetsExistInDefaultTree(t *testing.T) {
-	tmpHome(t)
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-
-	_, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		WithoutPlugins(),
-	)
-	var fragments []rootHelpFragment
-	for _, section := range rootLongSections {
-		fragments = append(fragments, section.fragments...)
-	}
-	fragments = append(fragments, rootUsageSynopsis...)
-	for _, fragment := range fragments {
-		if fragment.target == "" {
-			continue
-		}
-		if command := findByPath(root, string(fragment.target)); command == nil {
-			t.Errorf("root-help target %q does not resolve in the default command tree", fragment.target)
-		}
-	}
-}
-
-func TestPresentationKeepsDefaultRootHelpByteStable(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli", Long: rootLong}
-	root.SetUsageTemplate(rootUsageTemplate)
-	wantLong, wantUsage := root.Long, root.UsageTemplate()
-
-	applyPresentationAffordances(root, nil)
-
-	if root.Long != wantLong {
-		t.Fatalf("default root Long changed:\nwant:\n%s\n\ngot:\n%s", wantLong, root.Long)
-	}
-	if root.UsageTemplate() != wantUsage {
-		t.Fatalf("default root usage template changed:\nwant:\n%s\n\ngot:\n%s", wantUsage, root.UsageTemplate())
-	}
-}
-
-func TestHelpRejectsDescendantOfConcealedParent(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	parent := &cobra.Command{Use: "apps"}
-	child := &cobra.Command{Use: "+db-execute", RunE: func(*cobra.Command, []string) error { return nil }}
-	parent.AddCommand(child)
-	root.AddCommand(parent)
-	installUnavailableProjection(parent, "apps", cmdpolicy.Denial{}, "not shipped")
-	installHelpCommand(root)
-
-	help := findByPath(root, "help")
-	if help == nil || help.RunE == nil {
-		t.Fatal("help command not installed")
-	}
-	err := help.RunE(help, []string{"apps", "+db-execute"})
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) ||
-		validation.Subtype != errs.SubtypeCommandUnavailable ||
-		validation.Message != "not shipped" {
-		t.Fatalf("help descendant error = %#v, want command_unavailable inherited from parent", err)
-	}
-}
-
-func TestHidePolicyDiagnosticsIsHostPresentationOnly(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"config/**"}, nil)
-
-	runtime, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(HidePolicyDiagnostics()),
-	)
-	for _, path := range []string{
-		"config",
-		"config/policy",
-		"config/policy/show",
-		"config/plugins",
-		"config/plugins/show",
-	} {
-		cmd := findByPath(root, path)
-		if cmd == nil || cmd.RunE == nil {
-			t.Fatalf("%s missing unavailable projection", path)
-		}
-		err := cmd.RunE(cmd, nil)
-		var validation *errs.ValidationError
-		if !errors.As(err, &validation) ||
-			validation.Subtype != errs.SubtypeCommandUnavailable {
-			t.Errorf("%s error = %v, want command_unavailable", path, err)
-		}
-		if !runtime.surface.IsConcealed(surface.CommandID(path)) {
-			t.Errorf("%s not recorded in build-local surface", path)
-		}
-	}
-
-	// Synthetic presentation decisions must not be reported as policy facts.
-	active := cmdpolicy.GetActive()
-	if active == nil {
-		t.Fatal("missing active enforcement policy")
-	}
-	if _, exists := active.DeniedByPath["config/policy/show"]; exists {
-		t.Errorf("presentation-only diagnostic concealment leaked into ActivePolicy: %+v", active)
-	}
-}
-
-func TestConcealedBuildOmitsEmptyRootGroup(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{
-		"auth", "auth/**",
-		"config", "config/**",
-		"profile", "profile/**",
-		"doctor",
-		"update",
-	}, nil)
-
-	_, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(HidePolicyDiagnostics()),
-	)
-	var help bytes.Buffer
-	root.SetOut(&help)
-	root.SetErr(&help)
-	if err := root.Help(); err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(help.String(), "CLI management:") {
-		t.Errorf("empty management group leaked into help:\n%s", help.String())
-	}
-	if !strings.Contains(help.String(), "Agent tooling:") {
-		t.Errorf("non-empty tooling group disappeared:\n%s", help.String())
-	}
-
-	// Cobra's Execute path validates GroupID definitions before parsing flags.
-	// Calling root.Help directly does not exercise this invariant.
-	help.Reset()
-	root.SetOut(&help)
-	root.SetErr(&help)
-	root.SetArgs([]string{"--help"})
-	if err := root.Execute(); err != nil {
-		t.Fatalf("concealed root Execute --help: %v", err)
-	}
-	if strings.Contains(help.String(), "CLI management:") {
-		t.Errorf("empty management group leaked through Execute:\n%s", help.String())
-	}
-}
-
-func TestRecoveryRenderingUsesExactBuildLocalSurfaceAndDoesNotMutate(t *testing.T) {
-	tmpHome(t)
-	previousWorkspace := core.CurrentWorkspace()
-	core.SetCurrentWorkspace(core.WorkspaceLocal)
-	t.Cleanup(func() { core.SetCurrentWorkspace(previousWorkspace) })
-
-	registerRestriction(t, []string{"config/init"}, nil)
-	concealedRuntime, _, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(),
-	)
-
-	platform.ResetForTesting()
-	defaultRuntime, _, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		WithoutPlugins(),
-	)
-
-	if concealedRuntime.surface.CanReference(surface.CommandConfigInit) {
-		t.Fatal("config/init should be concealed")
-	}
-	if !concealedRuntime.surface.CanReference(surface.CommandConfigStrictMode) {
-		t.Fatal("exact leaf concealment incorrectly removed config/strict-mode")
-	}
-
-	original := core.NotConfiguredError()
-	originalProblem, ok := errs.ProblemOf(original)
-	if !ok || originalProblem.Hint == "" {
-		t.Fatalf("invalid test error: %v", original)
-	}
-	wantHint := originalProblem.Hint
-
-	concealed := concealedRuntime.recovery.Render(original)
-	concealedProblem, _ := errs.ProblemOf(concealed)
-	if strings.Contains(concealedProblem.Hint, "config init") ||
-		!strings.Contains(concealedProblem.Hint, "configure this distribution") {
-		t.Errorf("concealed tree did not use target-free recovery fallback: %q", concealedProblem.Hint)
-	}
-	if originalProblem.Hint != wantHint {
-		t.Fatalf("rendering mutated source hint: %q -> %q", wantHint, originalProblem.Hint)
-	}
-
-	visible := defaultRuntime.recovery.Render(original)
-	visibleProblem, _ := errs.ProblemOf(visible)
-	if visibleProblem.Hint != wantHint {
-		t.Errorf("default tree lost recovery after second Build: %q", visibleProblem.Hint)
-	}
-}
-
-func TestConcurrentBuildsKeepIndependentSurfacePlans(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"config/init"}, nil)
-	inv := buildInvocationForTest(t)
-
-	const pairs = 4
-	type result struct {
-		concealed bool
-		state     surface.CommandState
-	}
-	results := make(chan result, pairs*2)
-	start := make(chan struct{})
-	var wg sync.WaitGroup
-	for i := 0; i < pairs; i++ {
-		wg.Add(2)
-		go func() {
-			defer wg.Done()
-			<-start
-			runtime, _, _ := buildInternal(
-				context.Background(),
-				inv,
-				ConcealRestrictedCommands(),
-			)
-			results <- result{concealed: true, state: runtime.surface.State(surface.CommandConfigInit)}
-		}()
-		go func() {
-			defer wg.Done()
-			<-start
-			runtime, _, _ := buildInternal(
-				context.Background(),
-				inv,
-				WithoutPlugins(),
-			)
-			results <- result{state: runtime.surface.State(surface.CommandConfigInit)}
-		}()
-	}
-	close(start)
-	wg.Wait()
-	close(results)
-
-	for got := range results {
-		want := surface.CommandAvailable
-		if got.concealed {
-			want = surface.CommandConcealed
-		}
-		if got.state != want {
-			t.Errorf("concealed=%v state=%v, want %v", got.concealed, got.state, want)
-		}
-	}
-}
-
-func TestUpdateAffordancesDisappearWithoutDroppingIndependentRecovery(t *testing.T) {
-	update.SetPending(&update.UpdateInfo{Current: "1.0.0", Latest: "2.0.0"})
-	skillscheck.SetPending(&skillscheck.StaleNotice{Current: "1.0.0", Target: "2.0.0"})
-	deprecation.SetPending(&deprecation.Notice{
-		Command:     "+read",
-		Replacement: "+cells-get",
-		Skill:       "lark-sheets",
-	})
-	t.Cleanup(func() {
-		update.SetPending(nil)
-		skillscheck.SetPending(nil)
-		deprecation.SetPending(nil)
-	})
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandUpdate: surface.CommandConcealed,
-	})
-	got := composePendingNotice(plan)
-	if got == nil {
-		t.Fatal("independent deprecation recovery was dropped")
-	}
-	if _, exists := got["update"]; exists {
-		t.Errorf("update notice survived concealed update: %+v", got)
-	}
-	if _, exists := got["skills"]; exists {
-		t.Errorf("skills drift notice survived concealed update: %+v", got)
-	}
-	entry, ok := got["deprecated_command"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("missing deprecated_command: %+v", got)
-	}
-	if entry["replacement"] != "+cells-get" || entry["skill"] != "lark-sheets" {
-		t.Errorf("independent deprecation fields lost: %+v", entry)
-	}
-	if _, exists := entry["action"]; exists {
-		t.Errorf("unavailable update action survived: %+v", entry)
-	}
-	if strings.Contains(entry["message"].(string), "lark-cli update") {
-		t.Errorf("dead update pointer survived in message: %+v", entry)
-	}
-}
-
-func TestSetupNoticesDoesNoProviderWorkWhenUpdateIsConcealed(t *testing.T) {
-	oldCheck, oldRefresh, oldSkills := checkCachedUpdate, refreshUpdateCache, initializeSkillsCheck
-	oldPending := output.PendingNotice
-	t.Cleanup(func() {
-		checkCachedUpdate, refreshUpdateCache, initializeSkillsCheck = oldCheck, oldRefresh, oldSkills
-		output.PendingNotice = oldPending
-	})
-
-	var checks, refreshes, skillChecks int
-	checkCachedUpdate = func(string) *update.UpdateInfo {
-		checks++
-		return nil
-	}
-	refreshUpdateCache = func(string) { refreshes++ }
-	initializeSkillsCheck = func(string) { skillChecks++ }
-
-	setupNotices(surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandUpdate: surface.CommandConcealed,
-	}))
-	if checks != 0 || refreshes != 0 || skillChecks != 0 {
-		t.Fatalf("concealed update performed provider work: cache=%d refresh=%d skills=%d",
-			checks, refreshes, skillChecks)
-	}
-}
-
-func TestExecuteProfileBootstrapPreservesDefaultAndDefersOnlyForOptIn(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
-	t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
-
-	t.Run("default remains plain exit one", func(t *testing.T) {
-		tmpHome(t)
-		platform.ResetForTesting()
-		t.Cleanup(platform.ResetForTesting)
-
-		code, stdout, stderr := executeWithCapturedOS(t, nil, "--profile")
-		if code != 1 || stdout != "" ||
-			stderr != "Error: flag needs an argument: --profile\n" {
-			t.Fatalf("default --profile: exit=%d stdout=%q stderr=%q", code, stdout, stderr)
-		}
-	})
-
-	t.Run("opt-in concealed profile is an unknown flag", func(t *testing.T) {
-		tmpHome(t)
-		registerRestriction(t, []string{"profile", "profile/**"}, nil)
-
-		code, _, stderr := executeWithCapturedOS(
-			t,
-			[]BuildOption{ConcealRestrictedCommands()},
-			"--profile",
-		)
-		if code != 2 ||
-			!strings.Contains(stderr, `"subtype": "invalid_argument"`) ||
-			!strings.Contains(stderr, `unknown flag \"--profile\"`) {
-			t.Fatalf("concealed --profile: exit=%d stderr=%s", code, stderr)
-		}
-	})
-}
-
-func TestExecuteWithOptionsAppliesEachBuildOptionOnce(t *testing.T) {
-	tmpHome(t)
-	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
-	t.Setenv("LARKSUITE_CLI_NO_SKILLS_NOTIFIER", "1")
-	platform.ResetForTesting()
-	t.Cleanup(platform.ResetForTesting)
-
-	var applied int
-	option := BuildOption(func(*buildConfig) { applied++ })
-	code, _, stderr := executeWithCapturedOS(t, []BuildOption{option}, "--version")
-	if code != 0 {
-		t.Fatalf("--version exit=%d stderr=%s", code, stderr)
-	}
-	if applied != 1 {
-		t.Fatalf("BuildOption applied %d times, want exactly once", applied)
-	}
-}
-
-func TestConcealmentHelpIsOutsideBusinessHooks(t *testing.T) {
-	tmpHome(t)
-	var observed, wrapped int
-	registerRestriction(t, []string{"skills/read"}, func(builder *platform.Builder) *platform.Builder {
-		return builder.
-			Observer(platform.Before, "observe", platform.All(), func(context.Context, platform.Invocation) {
-				observed++
-			}).
-			Wrap("wrap", platform.All(), func(next platform.Handler) platform.Handler {
-				return func(ctx context.Context, inv platform.Invocation) error {
-					wrapped++
-					return next(ctx, inv)
-				}
-			})
-	})
-
-	_, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(),
-	)
-	help := findByPath(root, "help")
-	err := help.RunE(help, []string{"skills", "read"})
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) ||
-		validation.Subtype != errs.SubtypeCommandUnavailable {
-		t.Fatalf("help error = %v", err)
-	}
-	if observed != 0 || wrapped != 0 {
-		t.Fatalf("help entered business hooks: observed=%d wrapped=%d", observed, wrapped)
-	}
-}
-
-func TestWrapperCannotSwallowConcealedCommandEnforcement(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"skills/read"}, func(builder *platform.Builder) *platform.Builder {
-		return builder.Wrap("swallow", platform.All(), func(platform.Handler) platform.Handler {
-			return func(context.Context, platform.Invocation) error { return nil }
-		})
-	})
-
-	_, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(),
-	)
-	leaf := findByPath(root, "skills/read")
-	err := leaf.RunE(leaf, nil)
-	var validation *errs.ValidationError
-	if !errors.As(err, &validation) ||
-		validation.Subtype != errs.SubtypeCommandUnavailable {
-		t.Fatalf("wrapper swallowed denial: %v", err)
-	}
-}
-
-func TestConcealedCommandLeavesFlagAndPositionalCompletion(t *testing.T) {
-	tmpHome(t)
-	registerRestriction(t, []string{"skills/read"}, nil)
-	_, root, _ := buildInternal(
-		context.Background(),
-		buildInvocationForTest(t),
-		ConcealRestrictedCommands(),
-	)
-
-	for _, args := range [][]string{
-		{"__complete", "skills", "read", "--"},
-		{"__complete", "skills", "read", ""},
-	} {
-		var out bytes.Buffer
-		root.SetOut(&out)
-		root.SetErr(&out)
-		root.SetArgs(args)
-		_ = root.Execute()
-		if strings.Contains(out.String(), "--json") || strings.Contains(out.String(), "lark-") {
-			t.Errorf("%v exposed concealed completion:\n%s", args, out.String())
-		}
-	}
-}
-
-func TestApplyStrictStubWinsOverPluginDenial(t *testing.T) {
-	root := newTestTree()
-	pruneForStrictMode(root, core.StrictModeBot)
-	stub := findCmd(root, "auth", "login")
-	if stub == nil {
-		t.Fatal("auth/login strict stub missing")
-	}
-
-	cmdpolicy.Apply(root, map[string]cmdpolicy.Denial{
-		"auth/login": {
-			Layer:        cmdpolicy.LayerPolicy,
-			PolicySource: "plugin:acme",
-		},
-	})
-	if got := stub.Annotations[cmdpolicy.AnnotationDenialLayer]; got != cmdpolicy.LayerStrictMode {
-		t.Fatalf("denial layer = %q, want strict_mode", got)
-	}
-	err := stub.RunE(stub, nil)
-	if err == nil || !strings.Contains(err.Error(), "strict mode") {
-		t.Errorf("double-restricted command lost strict-mode error: %v", err)
-	}
-}
-
-func executeWithCapturedOS(
-	t *testing.T,
-	opts []BuildOption,
-	args ...string,
-) (int, string, string) {
-	t.Helper()
-	oldArgs, oldStdout, oldStderr := os.Args, os.Stdout, os.Stderr
-	stdout, err := os.CreateTemp(t.TempDir(), "stdout")
-	if err != nil {
-		t.Fatal(err)
-	}
-	stderr, err := os.CreateTemp(t.TempDir(), "stderr")
-	if err != nil {
-		t.Fatal(err)
-	}
-	restored := false
-	restore := func() {
-		if restored {
-			return
-		}
-		restored = true
-		os.Args, os.Stdout, os.Stderr = oldArgs, oldStdout, oldStderr
-	}
-	defer restore()
-
-	os.Args = append([]string{"e2e-cli"}, args...)
-	os.Stdout, os.Stderr = stdout, stderr
-	code := ExecuteWithOptions(opts...)
-	restore()
-
-	if err := stdout.Close(); err != nil {
-		t.Fatal(err)
-	}
-	if err := stderr.Close(); err != nil {
-		t.Fatal(err)
-	}
-	stdoutData, err := os.ReadFile(stdout.Name())
-	if err != nil {
-		t.Fatal(err)
-	}
-	stderrData, err := os.ReadFile(stderr.Name())
-	if err != nil {
-		t.Fatal(err)
-	}
-	return code, string(stdoutData), string(stderrData)
-}

cmd/profile/profile.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/runtimeplan"
 )
 
 // NewCmdProfile creates the profile command with subcommands.
@@ -14,13 +15,26 @@ func NewCmdProfile(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "profile",
 		Short: "Manage configuration profiles",
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			// A child PersistentPreRunE shadows root's PersistentPreRun, so retain
+			// the invocation state used by structured error hints here.
+			cmd.SilenceUsage = true
+			f.CurrentCommand = cmd
+			return f.RequireCommandRuntimeCapabilities(cmd.Context(), cmd)
+		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.SetRuntimeCapabilities(cmd, runtimeplan.CapabilityLocalProfileMutation)
 	cmdutil.SetTips(cmd, []string{
 		"AI agents: Do NOT switch or remove profiles unless the user explicitly asks.",
 	})
 
-	cmd.AddCommand(NewCmdProfileList(f))
+	list := NewCmdProfileList(f)
+	// Listing profiles is read-only and remains useful for diagnostics under a
+	// managed credential runtime. Every other profile subcommand mutates local
+	// profile selection, config, or keychain state and inherits the parent gate.
+	cmdutil.SetRuntimeCapabilities(list)
+	cmd.AddCommand(list)
 	cmd.AddCommand(NewCmdProfileUse(f))
 	cmd.AddCommand(NewCmdProfileAdd(f))
 	cmd.AddCommand(NewCmdProfileRemove(f))

cmd/profile/profile_test.go

@@ -16,8 +16,6 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -183,47 +181,6 @@ func TestProfileRemoveRun_RemovesCurrentProfileAndSwitchesToFirstRemaining(t *te
 	}
 }
 
-func TestProfileRemoveRun_AddRecoveryUsesBuildLocalSurface(t *testing.T) {
-	setupProfileConfigDir(t)
-	multi := &core.MultiAppConfig{
-		CurrentApp: "only",
-		Apps: []core.AppConfig{{
-			Name:      "only",
-			AppId:     "app-only",
-			AppSecret: core.PlainSecret("secret-only"),
-			Brand:     core.BrandFeishu,
-		}},
-	}
-	if err := core.SaveMultiAppConfig(multi); err != nil {
-		t.Fatalf("SaveMultiAppConfig() error = %v", err)
-	}
-
-	source := profileRemoveRun(nil, "only")
-	var original *errs.ValidationError
-	if !errors.As(source, &original) {
-		t.Fatalf("profileRemoveRun() error = %T, want *errs.ValidationError", source)
-	}
-	const visibleHint = "add another profile first: lark-cli profile add"
-	if original.Hint != visibleHint {
-		t.Fatalf("producer hint = %q, want %q", original.Hint, visibleHint)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandProfileAdd: surface.CommandConcealed,
-	})
-	var concealed *errs.ValidationError
-	if rendered := recovery.Render(source, plan); !errors.As(rendered, &concealed) {
-		t.Fatalf("rendered error = %T, want *errs.ValidationError", rendered)
-	}
-	const fallback = "configure another profile through this distribution before removing the only profile"
-	if concealed.Hint != fallback {
-		t.Errorf("concealed hint = %q, want %q", concealed.Hint, fallback)
-	}
-	if original.Hint != visibleHint {
-		t.Errorf("concealed render mutated producer hint: %q", original.Hint)
-	}
-}
-
 func TestProfileRenameRun_UpdatesCurrentAndPreviousReferences(t *testing.T) {
 	setupProfileConfigDir(t)
 	multi := &core.MultiAppConfig{

cmd/profile/remove.go

@@ -14,7 +14,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // NewCmdProfileRemove creates the profile remove subcommand.
@@ -46,12 +45,8 @@ func profileRemoveRun(f *cmdutil.Factory, name string) error {
 	}
 
 	if len(multi.Apps) == 1 {
-		return recovery.Attach(
-			errs.NewValidationError(errs.SubtypeFailedPrecondition, "cannot remove the only profile"),
-			recovery.Join("",
-				recovery.Command(recovery.TargetProfileAdd, "add another profile first: lark-cli profile add"),
-			).WithFallback("configure another profile through this distribution before removing the only profile"),
-		)
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "cannot remove the only profile").
+			WithHint("add another profile first: lark-cli profile add")
 	}
 
 	app := &multi.Apps[idx]

cmd/profile/runtime_capabilities_test.go

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package profile
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/runtimeplan"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+type recordingProfileKeychain struct {
+	gets    int
+	sets    int
+	removes int
+}
+
+func (k *recordingProfileKeychain) Get(_, _ string) (string, error) {
+	k.gets++
+	return "", nil
+}
+
+func (k *recordingProfileKeychain) Set(_, _, _ string) error {
+	k.sets++
+	return nil
+}
+
+func (k *recordingProfileKeychain) Remove(_, _ string) error {
+	k.removes++
+	return nil
+}
+
+func TestProfileMutationCommandsAreDeniedBeforeLocalStateChanges(t *testing.T) {
+	denied := errs.NewValidationError(
+		errs.SubtypeFailedPrecondition,
+		"local credential management is unavailable in this runtime",
+	).WithHint("manage credentials through the active provider")
+	plan := runtimeplan.New(runtimeplan.Options{
+		Capabilities: func(capability runtimeplan.Capability) error {
+			if capability == runtimeplan.CapabilityLocalProfileMutation {
+				return denied
+			}
+			return nil
+		},
+	})
+
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "add",
+			args: []string{"add", "--name", "new", "--app-id", "app-new", "--app-secret-stdin"},
+		},
+		{
+			name: "use",
+			args: []string{"use", "target"},
+		},
+		{
+			name: "rename",
+			args: []string{"rename", "target", "renamed"},
+		},
+		{
+			name: "remove",
+			args: []string{"remove", "target"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			configDir := setupProfileConfigDir(t)
+			saveManagedGateFixture(t)
+			configPath := filepath.Join(configDir, "config.json")
+			before, err := vfs.ReadFile(configPath)
+			if err != nil {
+				t.Fatalf("ReadFile(before) error = %v", err)
+			}
+
+			f, _, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
+			f.IOStreams.In = strings.NewReader("must-not-be-read\n")
+			keychain := &recordingProfileKeychain{}
+			f.Keychain = keychain
+
+			cmd := NewCmdProfile(f)
+			cmd.SetArgs(tt.args)
+			err = cmd.Execute()
+			if !errors.Is(err, denied) {
+				t.Fatalf("Execute() error = %v, want denied runtime error", err)
+			}
+
+			after, readErr := vfs.ReadFile(configPath)
+			if readErr != nil {
+				t.Fatalf("ReadFile(after) error = %v", readErr)
+			}
+			if !bytes.Equal(after, before) {
+				t.Fatalf("config changed despite runtime denial:\nbefore: %s\nafter:  %s", before, after)
+			}
+			if keychain.gets != 0 || keychain.sets != 0 || keychain.removes != 0 {
+				t.Fatalf("keychain calls = get:%d set:%d remove:%d, want none",
+					keychain.gets, keychain.sets, keychain.removes)
+			}
+		})
+	}
+}
+
+func TestProfileListRemainsAvailableWhenLocalMutationIsDenied(t *testing.T) {
+	setupProfileConfigDir(t)
+	saveManagedGateFixture(t)
+	plan := runtimeplan.New(runtimeplan.Options{
+		Capabilities: func(capability runtimeplan.Capability) error {
+			if capability == runtimeplan.CapabilityLocalProfileMutation {
+				return errs.NewValidationError(
+					errs.SubtypeFailedPrecondition,
+					"local credential management is unavailable in this runtime",
+				)
+			}
+			return nil
+		},
+	})
+	f, stdout, _, _ := cmdutil.TestFactoryWithRuntimePlan(t, nil, plan)
+
+	cmd := NewCmdProfile(f)
+	cmd.SetArgs([]string{"list"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("profile list was blocked by mutation capability: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"name": "default"`) {
+		t.Fatalf("profile list output = %s, want default profile", stdout.String())
+	}
+}
+
+func TestProfileMutationCommandsRemainAvailableByDefault(t *testing.T) {
+	setupProfileConfigDir(t)
+	saveManagedGateFixture(t)
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	// origin/main allows Profile preparation while an environment/extension
+	// provider is active. The managed runtime blocks this through its explicit
+	// plan policy; generic provider ownership must not change Standard.
+	f.Credential = credential.NewCredentialProvider(
+		[]extcred.Provider{profileEnvironmentProvider{}},
+		nil,
+		nil,
+		nil,
+	)
+
+	cmd := NewCmdProfile(f)
+	args := []string{"use", "target"}
+	matched, _, err := cmd.Find(args)
+	if err != nil {
+		t.Fatalf("Find() error = %v", err)
+	}
+	cmd.SetArgs(args)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("profile use with default runtime plan error = %v", err)
+	}
+	if f.CurrentCommand != matched {
+		t.Fatalf("CurrentCommand = %v, want matched command %v", f.CurrentCommand, matched)
+	}
+
+	saved, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig() error = %v", err)
+	}
+	if saved.CurrentApp != "target" || saved.PreviousApp != "default" {
+		t.Fatalf("selection = current:%q previous:%q, want target/default",
+			saved.CurrentApp, saved.PreviousApp)
+	}
+}
+
+type profileEnvironmentProvider struct{}
+
+func (profileEnvironmentProvider) Name() string { return "env" }
+
+func (profileEnvironmentProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
+	return &extcred.Account{
+		AppID:               "cli_environment",
+		Brand:               extcred.BrandFeishu,
+		SupportedIdentities: extcred.SupportsAll,
+	}, nil
+}
+
+func (profileEnvironmentProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
+	return &extcred.Token{Value: "environment-token"}, nil
+}
+
+func saveManagedGateFixture(t *testing.T) {
+	t.Helper()
+	multi := &core.MultiAppConfig{
+		CurrentApp: "default",
+		Apps: []core.AppConfig{
+			{
+				Name:      "default",
+				AppId:     "app-default",
+				AppSecret: core.PlainSecret("secret-default"),
+				Brand:     core.BrandFeishu,
+			},
+			{
+				Name:  "target",
+				AppId: "app-target",
+				AppSecret: core.SecretInput{Ref: &core.SecretRef{
+					Source: "keychain",
+					ID:     "appsecret:app-target",
+				}},
+				Brand: core.BrandLark,
+			},
+		},
+	}
+	if err := core.SaveMultiAppConfig(multi); err != nil {
+		t.Fatalf("SaveMultiAppConfig() error = %v", err)
+	}
+}

cmd/prune.go

@@ -13,7 +13,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // pruneForStrictMode removes commands incompatible with the active strict mode.
@@ -106,16 +105,9 @@ func strictModeStubFrom(child *cobra.Command, mode core.StrictMode) *cobra.Comma
 		},
 		RunE: func(c *cobra.Command, _ []string) error {
 			cd := cmdpolicy.CommandDeniedFromDenial(cmdpolicy.CanonicalPath(c), denial)
-			hint := recovery.Join("; ",
-				recovery.Text(fmt.Sprintf("denied by %s policy (reason_code %s)", cd.Layer, cd.ReasonCode)),
-				recovery.Command(recovery.TargetConfigStrictMode, stubHint),
-			)
-			return recovery.Annotate(
-				errs.NewValidationError(errs.SubtypeFailedPrecondition, "%s", stubMessage).
-					WithHint("%s", hint.String()).
-					WithCause(cd),
-				hint,
-			)
+			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "%s", stubMessage).
+				WithHint("denied by %s policy (reason_code %s); %s", cd.Layer, cd.ReasonCode, stubHint).
+				WithCause(cd)
 		},
 	}
 }

cmd/prune_test.go

@@ -14,8 +14,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/spf13/cobra"
 )
 
@@ -381,48 +379,3 @@ func TestStrictModeStub_PreservesOriginalMetadata(t *testing.T) {
 		t.Errorf("denial annotation overwritten or missing")
 	}
 }
-
-// The strict-mode stub carries a targeted config/strict-mode action alongside
-// non-command policy context. Rendering for a concealed tree drops only the
-// dead pointer and does not mutate the source error.
-func TestStrictModeStub_ConfigHintUsesBuildLocalSurface(t *testing.T) {
-	child := &cobra.Command{Use: "search", RunE: func(*cobra.Command, []string) error { return nil }}
-	stub := strictModeStubFrom(child, core.StrictModeBot)
-	source := stub.RunE(stub, nil)
-	var original *errs.ValidationError
-	if !errors.As(source, &original) {
-		t.Fatalf("expected *errs.ValidationError, got %T %v", source, source)
-	}
-	if original.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("subtype = %q, want failed_precondition", original.Subtype)
-	}
-	if !strings.Contains(original.Hint, "config strict-mode") {
-		t.Fatalf("producer hint = %q, want config strict-mode", original.Hint)
-	}
-
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandConfigStrictMode: surface.CommandConcealed,
-	})
-	var concealed *errs.ValidationError
-	if rendered := recovery.Render(source, plan); !errors.As(rendered, &concealed) {
-		t.Fatalf("rendered error = %T, want *errs.ValidationError", rendered)
-	}
-	if concealed == original {
-		t.Fatal("Render must clone the typed error")
-	}
-	if strings.Contains(concealed.Hint, "config strict-mode") {
-		t.Errorf("concealed hint still contains config strict-mode: %q", concealed.Hint)
-	}
-	if !strings.Contains(concealed.Hint, "reason_code identity_not_supported") {
-		t.Errorf("non-command policy guidance was lost: %q", concealed.Hint)
-	}
-
-	var visible *errs.ValidationError
-	if !errors.As(recovery.Render(source, nil), &visible) ||
-		!strings.Contains(visible.Hint, "config strict-mode") {
-		t.Errorf("visible render must keep config strict-mode, got %+v", visible)
-	}
-	if !strings.Contains(original.Hint, "config strict-mode") {
-		t.Errorf("concealed render mutated source hint: %q", original.Hint)
-	}
-}

cmd/root.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"io/fs"
 	"os"
 	"sort"
 	"strings"
@@ -22,16 +21,71 @@ import (
 	"github.com/larksuite/cli/internal/deprecation"
 	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/skillref"
+	"github.com/larksuite/cli/internal/runtimebootstrap"
 	"github.com/larksuite/cli/internal/skillscheck"
 	"github.com/larksuite/cli/internal/suggest"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
+const rootLong = `lark-cli — Lark/Feishu CLI tool.
+
+AGENT QUICKSTART (driving this as an agent? start here):
+    Browse commands:  lark-cli <domain> --help            # +shortcuts (preferred) and raw API resources
+    Inspect a call:   lark-cli schema <service>.<resource>.<method>   # params, types, scopes, examples
+    Prefer a +shortcut over the raw API resource when one matches the task.
+    Risk: each command's --help shows read | write | high-risk-write;
+          high-risk-write needs --yes, only after the user confirms.
+    On any API call: --jq <expr> filters JSON output, --dry-run previews the request (runs nothing).
+
+EXAMPLES (one per command style, in order of preference):
+    lark-cli calendar +agenda                                       # +shortcut — a high-level task, prefer these
+    lark-cli mail user_mailbox.messages list --user-mailbox-id me   # typed command for one API method
+    lark-cli schema mail.user_mailbox.messages.list                 # inspect a method's params before calling
+    lark-cli api GET /open-apis/calendar/v4/calendars               # raw escape hatch — any endpoint by HTTP path`
+
+// rootUsageTemplate is cobra's default usage template with two root-only
+// additions gated on {{if not .HasParent}}: a curated multi-form Usage synopsis
+// (replacing cobra's generic "[flags] / [command]") and a human skills-setup
+// footer. Subcommands render the stock template unchanged. The rest is verbatim
+// cobra so the command groups and flags are untouched.
+const rootUsageTemplate = `{{if .HasParent}}Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{else}}Usage:
+  lark-cli <command> [subcommand] [method] [flags]
+  lark-cli api <method> <path> [--params <json>] [--data <json>]
+  lark-cli schema <service.resource.method>{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}
+
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}{{if not .HasParent}}
+
+Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://github.com/larksuite/cli#agent-skills{{end}}
+`
+
 // Execute runs the root command and returns the process exit code.
 // rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
 // UnknownFlags whitelist (installUnknownSubcommandGuard) swallows unknown flags
@@ -41,69 +95,32 @@ import (
 var rawInvocationArgs []string
 
 func Execute() int {
-	return executeWithOptions(nil)
-}
-
-// ExecuteWithOptions is the standard entrypoint for wrapper distributions that
-// need host-level Build options such as ConcealRestrictedCommands. Execute
-// intentionally keeps its original non-variadic signature for source
-// compatibility with callers that store it as a func() int value.
-func ExecuteWithOptions(opts ...BuildOption) int {
-	return executeWithOptions(opts)
-}
-
-func executeWithOptions(opts []BuildOption) int {
 	rawInvocationArgs = os.Args[1:]
-	inv, bootstrapErr := BootstrapInvocationContext(os.Args[1:])
-	cfg := &buildConfig{}
-	for _, opt := range opts {
-		if opt != nil {
-			opt(cfg)
-		}
-	}
-	deferProfileError := cfg.presentation.enabled &&
-		isDeferredBootstrapProfileError(bootstrapErr)
-	if bootstrapErr != nil && !deferProfileError {
-		fmt.Fprintln(os.Stderr, "Error:", bootstrapErr)
+	inv, err := BootstrapInvocationContext(os.Args[1:])
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "Error:", err)
 		return 1
 	}
-	if cfg.streams == nil {
-		WithIO(os.Stdin, os.Stdout, os.Stderr)(cfg)
-	}
-	if !cfg.hideProfileSet {
-		HideProfile(isSingleAppMode())(cfg)
-	}
-	if !cfg.startupBrandSet {
-		WithStartupBrand(ResolveStartupBrand(inv.Profile))(cfg)
-	}
+	// Resolve all startup state from the detected workspace. This must happen
+	// before ResolveStartupBrand, isSingleAppMode, or buildInternal reads
+	// workspace-scoped configuration.
+	selectInvocationWorkspace()
+	startup := runtimebootstrap.Resolve(inv.Profile)
+	startupBrand := resolveStartupBrandFromConfig(inv.Profile, startup.ProfileConfig)
 	configureFlagCompletions(os.Args)
 
 	ctx := context.Background()
-	if deferProfileError {
-		cfg.deferStartup = true
-	}
-	runtime, rootCmd, reg := buildInternalWithConfig(ctx, inv, cfg)
-	f := runtime.Factory
-
-	if deferProfileError {
-		if runtime.surface.CanReference(surface.CommandProfile) {
-			// The completed distribution still ships --profile. Replay the
-			// exact pre-Build legacy failure and do not emit Startup, notices,
-			// or Shutdown for an invocation that never passed bootstrap.
-			fmt.Fprintln(os.Stderr, "Error:", bootstrapErr)
-			return 1
-		}
-		if reg != nil {
-			if err := emitStartup(ctx, reg); err != nil {
-				installPluginLifecycleErrorGuard(rootCmd, err)
-				reg = nil
-			}
-		}
-	}
+	f, rootCmd, reg := buildInternal(
+		ctx, inv,
+		WithIO(os.Stdin, os.Stdout, os.Stderr),
+		HideProfile(isSingleAppMode()),
+		WithStartupBrand(startupBrand),
+		withRuntimeBootstrap(startup),
+	)
 
 	// --- Notices (non-blocking) ---
 	if !isCompletionCommand(os.Args) {
-		setupNotices(runtime.surface)
+		setupNotices()
 	}
 
 	runErr := rootCmd.Execute()
@@ -117,98 +134,69 @@ func executeWithOptions(opts []BuildOption) int {
 	}
 
 	if runErr != nil {
-		return handleRootError(f, runErr, runtime.recovery)
+		return handleRootError(f, runErr)
 	}
 	return 0
 }
 
-// isDeferredBootstrapProfileError identifies the one bootstrap parse failure
-// an explicitly concealed distribution may need the completed tree to render.
-// Default and legacy builds never defer it.
-func isDeferredBootstrapProfileError(err error) bool {
-	return err != nil && err.Error() == "flag needs an argument: --profile"
-}
-
-// Notice provider seams keep the "concealed update means no cache, network, or
-// skills-state access" contract directly testable. Production always uses the
-// concrete implementations below.
-var (
-	checkCachedUpdate     = update.CheckCached
-	refreshUpdateCache    = update.RefreshCache
-	initializeSkillsCheck = skillscheck.Init
-)
-
 // setupNotices wires both the binary update notice and the skills
 // staleness notice into output.PendingNotice as a composed function.
 // Each provider populates an independent key under _notice; either
 // or both may be present in any given envelope.
-func setupNotices(plan *surface.Plan) {
-	if plan.CanReference(surface.CommandUpdate) {
-		// Binary update — synchronous cache check + async refresh.
-		if info := checkCachedUpdate(build.Version); info != nil {
-			update.SetPending(info)
-		}
-		ver := build.Version
-		go func() {
-			defer func() {
-				if r := recover(); r != nil {
-					fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
-				}
-			}()
-			refreshUpdateCache(ver)
-			if update.GetPending() == nil {
-				if info := checkCachedUpdate(ver); info != nil {
-					update.SetPending(info)
-				}
+func setupNotices() {
+	// Binary update — synchronous cache check + async refresh
+	if info := checkCachedEditionUpdate(build.Version); info != nil {
+		update.SetPending(info)
+	}
+	ver := build.Version
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				fmt.Fprintf(os.Stderr, "update check panic: %v\n", r)
 			}
 		}()
+		refreshEditionUpdateCache(ver)
+		if update.GetPending() == nil {
+			if info := checkCachedEditionUpdate(ver); info != nil {
+				update.SetPending(info)
+			}
+		}
+	}()
 
-		// Skills drift has only one recovery action: lark-cli update. Do not
-		// even inspect local drift state when that action is absent.
-		initializeSkillsCheck(build.Version)
-	}
+	// Skills check — synchronous, local-only (no network, no goroutine).
+	skillscheck.Init(build.Version)
 
-	// Capture this build's immutable plan; never consult another Build's state.
-	output.PendingNotice = func() map[string]interface{} {
-		return composePendingNotice(plan)
-	}
+	// Composed notice provider — emits keys only when each pending is set.
+	output.PendingNotice = composePendingNotice
 }
 
 // composePendingNotice merges all process-level pending notices (available
 // update, skills/binary drift, deprecated-command alias) into the map surfaced
 // as the JSON "_notice" envelope field. Returns nil when nothing is pending.
 // Extracted from Execute so the composition is unit-testable.
-func composePendingNotice(plan *surface.Plan) map[string]interface{} {
+func composePendingNotice() map[string]interface{} {
 	notice := map[string]interface{}{}
-	canUpdate := plan.CanReference(surface.CommandUpdate)
-	// Update and skills-drift notices have no recovery path of their own:
-	// both exist solely to steer the caller to `lark-cli update`.
-	if canUpdate {
-		if info := update.GetPending(); info != nil {
-			notice["update"] = map[string]interface{}{
-				"current": info.Current,
-				"latest":  info.Latest,
-				"message": info.Message(),
-				"command": "lark-cli update",
-			}
+	if info := update.GetPending(); info != nil {
+		notice["update"] = map[string]interface{}{
+			"current": info.Current,
+			"latest":  info.Latest,
+			"message": info.Message(),
+			"command": "lark-cli update",
 		}
-		if stale := skillscheck.GetPending(); stale != nil {
-			notice["skills"] = map[string]interface{}{
-				"current": stale.Current,
-				"target":  stale.Target,
-				"message": stale.Message(),
-				"command": "lark-cli update",
-			}
+	}
+	if stale := skillscheck.GetPending(); stale != nil {
+		notice["skills"] = map[string]interface{}{
+			"current": stale.Current,
+			"target":  stale.Target,
+			"message": stale.Message(),
+			"command": "lark-cli update",
 		}
 	}
 	if dep := deprecation.GetPending(); dep != nil {
 		entry := map[string]interface{}{
 			"command": dep.Command,
-			"message": dep.MessageWithoutUpdateAction(),
-		}
-		if canUpdate {
-			entry["message"] = dep.Message()
-			entry["action"] = "lark-cli update"
+			"message": dep.Message(),
+			"action":  "lark-cli update",
 		}
 		if dep.Replacement != "" {
 			entry["replacement"] = dep.Replacement
@@ -265,22 +253,15 @@ func configureFlagCompletions(args []string) {
 //     argument validation): typed as an invalid_argument envelope (exit 2),
 //     matching the explicit flag/subcommand guards. Flag parse errors are
 //     already typed upstream by the root FlagErrorFunc.
-func handleRootError(
-	f *cmdutil.Factory,
-	err error,
-	projector *recovery.Projector,
-) int {
+func handleRootError(f *cmdutil.Factory, err error) int {
 	errOut := f.IOStreams.ErrOut
-	renderedErr := err
 
 	// When the typed error is a need_user_authorization signal, fold in the
 	// current command's declared scopes as a Hint so the user/AI sees the
 	// concrete scope(s) to re-auth with. The hint is computed on the fly from
-	// local shortcut/service metadata. Both semantic recovery filtering and
-	// dynamic enrichment operate on a concrete clone, never the producer's
-	// reusable error value.
+	// local shortcut/service metadata — it never depends on server state.
 	if !errs.IsRaw(err) {
-		renderedErr = newRootErrorPresenter(f, projector).Present(err)
+		applyNeedAuthorizationHint(f, err)
 	}
 
 	// Staged dispatch: capture the typed exit code BEFORE attempting the
@@ -291,7 +272,7 @@ func handleRootError(
 	// WriteTypedErrorEnvelope still returns false when err carries no
 	// Problem; in that case we fall through to the signal / plain-text paths.
 	typedExit := output.ExitCodeOf(err)
-	if output.WriteTypedErrorEnvelope(errOut, renderedErr, string(f.ResolvedIdentity)) {
+	if output.WriteTypedErrorEnvelope(errOut, err, string(f.ResolvedIdentity)) {
 		return typedExit
 	}
 
@@ -584,10 +565,15 @@ const (
 	groupManagement = "cli-management"
 )
 
-// classifyRootCommands assigns root children to help groups after registration.
-// Group definitions are attached separately, after optional distribution
-// projection, so a concealed build can omit a now-empty heading.
-func classifyRootCommands(root *cobra.Command) {
+// groupRootCommands classifies root's direct children into the help groups,
+// called once after all commands are registered. Unclassified commands fall to
+// cobra's "Additional Commands" section.
+func groupRootCommands(root *cobra.Command) {
+	root.AddGroup(
+		&cobra.Group{ID: groupDomains, Title: "Lark domains:"},
+		&cobra.Group{ID: groupTooling, Title: "Agent tooling:"},
+		&cobra.Group{ID: groupManagement, Title: "CLI management:"},
+	)
 	tooling := map[string]bool{"api": true, "schema": true, "skills": true}
 	management := map[string]bool{"auth": true, "config": true, "profile": true, "doctor": true, "update": true}
 	for _, c := range root.Commands() {
@@ -605,46 +591,6 @@ func classifyRootCommands(root *cobra.Command) {
 	}
 }
 
-// finalizeRootCommandGroups attaches Cobra group definitions once. A group is
-// omitted only when this build's surface plan concealed all its children.
-// Hidden legacy/YAML commands remain referenceable and therefore keep the
-// historical (possibly empty) heading.
-func finalizeRootCommandGroups(root *cobra.Command, plan *surface.Plan) {
-	if root == nil || len(root.Groups()) != 0 {
-		return
-	}
-	groups := []*cobra.Group{
-		{ID: groupDomains, Title: "Lark domains:"},
-		{ID: groupTooling, Title: "Agent tooling:"},
-		{ID: groupManagement, Title: "CLI management:"},
-	}
-	for _, group := range groups {
-		if plan != nil && !rootGroupHasReferenceableChild(root, group.ID, plan) {
-			// Cobra validates that every non-empty child GroupID has a
-			// matching definition before dispatch, including hidden children.
-			// If presentation removes an entire group, clear those now-hidden
-			// assignments as well as omitting the heading.
-			for _, child := range root.Commands() {
-				if child.GroupID == group.ID {
-					child.GroupID = ""
-				}
-			}
-			continue
-		}
-		root.AddGroup(group)
-	}
-}
-
-func rootGroupHasReferenceableChild(root *cobra.Command, groupID string, plan *surface.Plan) bool {
-	for _, child := range root.Commands() {
-		if child.GroupID == groupID &&
-			plan.CanReference(surface.CommandID(cmdpolicy.CanonicalPath(child))) {
-			return true
-		}
-	}
-	return false
-}
-
 // isLarkDomain reports whether a root child is a Lark domain (service-sourced or
 // shortcut-tagged), not CLI tooling. Mirrors service.PrepareDomainHelp.
 func isLarkDomain(c *cobra.Command) bool {
@@ -663,15 +609,6 @@ func isLarkDomain(c *cobra.Command) bool {
 func flagDidYouMean(c *cobra.Command, ferr error) error {
 	name, isUnknown := unknownFlagName(ferr)
 	if !isUnknown {
-		// A policy-gated flag invoked bare ("flag needs an argument")
-		// never reaches its rejecting Value; it still presents as
-		// unregistered, exactly like a set one.
-		if gated, ok := gatedFlagFromNeedsArg(c, ferr); ok {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"unknown flag %q for %q", "--"+gated, c.CommandPath()).
-				WithParams(errs.InvalidParam{Name: "--" + gated, Reason: "unknown flag"}).
-				WithHint("run `%s --help` to see valid flags", c.CommandPath())
-		}
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", ferr.Error()).
 			WithHint("run `%s --help` for valid flags", c.CommandPath())
 	}
@@ -694,25 +631,6 @@ func flagDidYouMean(c *cobra.Command, ferr error) error {
 		WithHint("%s", hint)
 }
 
-// gatedFlagFromNeedsArg reports whether ferr is pflag's "flag needs an
-// argument: --name" for a policy-gated flag on this command's flag set.
-func gatedFlagFromNeedsArg(c *cobra.Command, ferr error) (string, bool) {
-	const p = "flag needs an argument: --"
-	msg := ferr.Error()
-	i := strings.Index(msg, p)
-	if i < 0 {
-		return "", false
-	}
-	name := msg[i+len(p):]
-	if j := strings.IndexAny(name, " \t"); j >= 0 {
-		name = name[:j]
-	}
-	if fl := c.Root().PersistentFlags().Lookup(name); isPolicyGatedFlag(fl) {
-		return name, true
-	}
-	return "", false
-}
-
 // unknownFlagName extracts the offending long-flag name from cobra's flag-parse
 // error text ("unknown flag: --query" → "query"). Returns ok=false for anything
 // else (missing argument, invalid value, unknown shorthand) so the caller keeps
@@ -749,59 +667,16 @@ func visibleFlagNames(c *cobra.Command) []string {
 	return names
 }
 
-// installHelpCommand upgrades Cobra's default help command so that
-// `lark-cli help <plugin-restricted-cmd>` returns a typed error (exit 2)
-// instead of printing an envelope and exiting 0 — cobra's stock help
-// command has no error channel.
-func installHelpCommand(root *cobra.Command) {
-	root.InitDefaultHelpCmd()
-	helpCmd := findByPath(root, "help")
-	if helpCmd == nil {
-		return
-	}
-	helpCmd.Run = nil
-	helpCmd.RunE = func(c *cobra.Command, args []string) error {
-		target, _, err := root.Find(args)
-		if err != nil || target == nil {
-			c.Printf("Unknown help topic %#q\n", args)
-			return root.Usage()
-		}
-		if msg, ok := unavailableHelpMessage(target); ok {
-			return errs.NewValidationError(errs.SubtypeCommandUnavailable, "%s", msg)
-		}
-		target.SetContext(c.Context())
-		target.InitDefaultHelpFlag()
-		target.InitDefaultVersionFlag()
-		return target.Help()
-	}
-	// help attaches after policy evaluation (framework meta command, never
-	// policy-evaluated). No risk annotation: it would render a "Risk:"
-	// line that stock cobra help output does not carry.
-	cmdutil.DisableAuthCheck(helpCmd)
-}
-
 // installTipsHelpFunc wraps the default help function to append a TIPS section
 // when a command has tips set via cmdutil.SetTips. It also force-shows global
 // flags that are normally hidden in single-app mode (currently --profile)
 // when rendering the root command's own help, so users discovering the CLI
 // still see them at `lark-cli --help`.
-//
-// skillContent is read lazily at help-render time (not captured up front) so
-// the domain-guide pointer reflects the resolved skill tree -- the same
-// f.SkillContent that `skills list`/`read` serve -- even though plugin skill
-// customization is applied after this help func is installed.
-func installTipsHelpFunc(
-	root *cobra.Command,
-	skillContent func() fs.FS,
-	skillReferences func() *skillref.Resolver,
-	projector *recovery.Projector,
-) {
+func installTipsHelpFunc(root *cobra.Command) {
 	defaultHelp := root.HelpFunc()
 	root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
 		if cmd == root {
-			// Force-show flags hidden by single-app mode; never a
-			// policy-retired one.
-			if f := root.PersistentFlags().Lookup("profile"); f != nil && f.Hidden && !isPolicyGatedFlag(f) {
+			if f := root.PersistentFlags().Lookup("profile"); f != nil && f.Hidden {
 				f.Hidden = false
 				defer func() { f.Hidden = true }()
 			}
@@ -809,22 +684,15 @@ func installTipsHelpFunc(
 		// Domain and method commands compose their agent guidance into Long lazily
 		// here (shortcuts attach after service registration); both skip the generic
 		// bottom-of-help append below.
-		var refs *skillref.Resolver
-		if skillReferences != nil {
-			refs = skillReferences()
-		}
-		content := skillContent()
-		if service.PrepareDomainHelpWithReferences(cmd, content, refs) {
+		if service.PrepareDomainHelp(cmd, embeddedSkillContent) {
 			defaultHelp(cmd, args)
 			return
 		}
-		if service.PrepareMethodHelpWithProjection(cmd, content, refs, func() bool {
-			return projector.CanReference(recovery.TargetSchema)
-		}) {
+		if service.PrepareMethodHelp(cmd, embeddedSkillContent) {
 			defaultHelp(cmd, args)
 			return
 		}
-		if service.PrepareShortcutHelpWithReferences(cmd, content, refs) {
+		if service.PrepareShortcutHelp(cmd, embeddedSkillContent) {
 			defaultHelp(cmd, args)
 			return
 		}

cmd/root_help.go

@@ -1,154 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"strings"
-
-	"github.com/larksuite/cli/internal/surface"
-)
-
-// rootHelpFragment is one framework-owned root-help fragment. A fragment with
-// a target is emitted only while that exact command remains referenceable in
-// this build. Keeping the target next to the text prevents curated examples
-// from becoming dead pointers in reduced distributions.
-type rootHelpFragment struct {
-	target surface.CommandID
-	text   string
-}
-
-// rootHelpSection keeps a heading coupled to the target-aware entries it
-// introduces. When projection removes every entry, the heading disappears
-// with them instead of leaving an empty section in reduced builds.
-type rootHelpSection struct {
-	heading   string
-	fragments []rootHelpFragment
-}
-
-const (
-	rootHelpAPI            surface.CommandID = "api"
-	rootHelpCalendarAgenda surface.CommandID = "calendar/+agenda"
-	rootHelpMailList       surface.CommandID = "mail/user_mailbox.messages/list"
-)
-
-var rootLongSections = []rootHelpSection{
-	{fragments: []rootHelpFragment{
-		{text: `lark-cli — Lark/Feishu CLI tool.
-
-AGENT QUICKSTART (driving this as an agent? start here):
-    Browse commands:  lark-cli <domain> --help            # +shortcuts (preferred) and raw API resources`},
-		{target: surface.CommandSchema, text: `
-    Inspect a call:   lark-cli schema <service>.<resource>.<method>   # params, types, scopes, examples`},
-		{text: `
-    Prefer a +shortcut over the raw API resource when one matches the task.
-    Risk: each command's --help shows read | write | high-risk-write;
-          high-risk-write needs --yes, only after the user confirms.
-    On any API call: --jq <expr> filters JSON output, --dry-run previews the request (runs nothing).`},
-	}},
-	{
-		heading: "\n\nEXAMPLES (one per command style, in order of preference):",
-		fragments: []rootHelpFragment{
-			{target: rootHelpCalendarAgenda, text: `
-    lark-cli calendar +agenda                                       # +shortcut — a high-level task, prefer these`},
-			{target: rootHelpMailList, text: `
-    lark-cli mail user_mailbox.messages list --user-mailbox-id me   # typed command for one API method`},
-			{target: surface.CommandSchema, text: `
-    lark-cli schema mail.user_mailbox.messages.list                 # inspect a method's params before calling`},
-			{target: rootHelpAPI, text: `
-    lark-cli api GET /open-apis/calendar/v4/calendars               # raw escape hatch — any endpoint by HTTP path`},
-		},
-	},
-}
-
-// rootLong is the fully-visible default text retained as a compatibility
-// oracle. Reduced builds derive their text from the same typed fragments.
-var rootLong = renderRootHelpSections(rootLongSections, nil)
-
-func renderRootHelpSections(sections []rootHelpSection, plan *surface.Plan) string {
-	var b strings.Builder
-	for _, section := range sections {
-		body := renderRootHelpFragments(section.fragments, plan)
-		if body == "" {
-			continue
-		}
-		b.WriteString(section.heading)
-		b.WriteString(body)
-	}
-	return b.String()
-}
-
-func renderRootHelpFragments(fragments []rootHelpFragment, plan *surface.Plan) string {
-	var b strings.Builder
-	for _, fragment := range fragments {
-		if fragment.target != "" && !plan.CanReference(fragment.target) {
-			continue
-		}
-		b.WriteString(fragment.text)
-	}
-	return b.String()
-}
-
-var rootUsageSynopsis = []rootHelpFragment{
-	{text: `Usage:
-  lark-cli <command> [subcommand] [method] [flags]`},
-	{target: rootHelpAPI, text: `
-  lark-cli api <method> <path> [--params <json>] [--data <json>]`},
-	{target: surface.CommandSchema, text: `
-  lark-cli schema <service.resource.method>`},
-}
-
-const rootUsageTemplatePrefix = `{{if .HasParent}}Usage:{{if .Runnable}}
-  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
-  {{.CommandPath}} [command]{{end}}{{else}}`
-
-// rootUsageTemplateSuffix is Cobra's default usage template after the root
-// synopsis. Root-only framework affordances are assembled separately above
-// and below it so each command reference carries an explicit target.
-const rootUsageTemplateSuffix = `{{end}}{{if gt (len .Aliases) 0}}
-
-Aliases:
-  {{.NameAndAliases}}{{end}}{{if .HasExample}}
-
-Examples:
-{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
-
-Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}
-
-{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
-
-Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
-
-Flags:
-{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
-
-Global Flags:
-{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
-
-Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
-  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
-
-Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}`
-
-// skillsSetupFooter is the root-help pointer at the human one-time skills
-// setup. It is emitted only while skills/read remains referenceable.
-const skillsSetupFooter = `{{if not .HasParent}}
-
-Skills setup (one-time, humans): npx skills add larksuite/cli -g -y — https://github.com/larksuite/cli#agent-skills{{end}}`
-
-var rootUsageTemplate = renderRootUsageTemplate(nil)
-
-func renderRootUsageTemplate(plan *surface.Plan) string {
-	var b strings.Builder
-	b.WriteString(rootUsageTemplatePrefix)
-	b.WriteString(renderRootHelpFragments(rootUsageSynopsis, plan))
-	b.WriteString(rootUsageTemplateSuffix)
-	if plan.CanReference(surface.CommandSkillsRead) {
-		b.WriteString(skillsSetupFooter)
-	}
-	b.WriteByte('\n')
-	return b.String()
-}

cmd/root_integration_test.go

@@ -59,7 +59,7 @@ func executeRootIntegration(t *testing.T, f *cmdutil.Factory, rootCmd *cobra.Com
 	t.Helper()
 	rootCmd.SetArgs(args)
 	if err := rootCmd.Execute(); err != nil {
-		return handleRootError(f, err, nil)
+		return handleRootError(f, err)
 	}
 	return 0
 }
@@ -505,7 +505,7 @@ func TestSetupNotices_ColdStart_NoNotice(t *testing.T) {
 		output.PendingNotice = nil
 	})
 
-	setupNotices(nil)
+	setupNotices()
 
 	notice := output.GetNotice()
 	if notice == nil {
@@ -539,7 +539,7 @@ func TestSetupNotices_InSync(t *testing.T) {
 		output.PendingNotice = nil
 	})
 
-	setupNotices(nil)
+	setupNotices()
 
 	notice := output.GetNotice()
 	if notice != nil {
@@ -572,7 +572,7 @@ func TestSetupNotices_Drift(t *testing.T) {
 		output.PendingNotice = nil
 	})
 
-	setupNotices(nil)
+	setupNotices()
 
 	notice := output.GetNotice()
 	if notice == nil {
@@ -621,7 +621,7 @@ func TestSetupNotices_BothUpdateAndSkills(t *testing.T) {
 		output.PendingNotice = nil
 	})
 
-	setupNotices(nil)
+	setupNotices()
 
 	// After setupNotices, skills pending is set (drift). Manually populate
 	// the update side so the composed envelope has both keys — the update

cmd/root_risk_help_test.go

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

cmd/root_test.go

@@ -18,6 +18,7 @@ import (
 	cmdconfig "github.com/larksuite/cli/cmd/config"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/errs"
+	extcred "github.com/larksuite/cli/extension/credential"
 	internalauth "github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
@@ -162,7 +163,7 @@ func TestHandleRootError_SecurityPolicyCanonicalEnvelope(t *testing.T) {
 			ChallengeURL: "https://example.com/challenge",
 		}
 
-		gotExit := handleRootError(f, spErr, nil)
+		gotExit := handleRootError(f, spErr)
 		if gotExit != int(output.ExitContentSafety) {
 			t.Errorf("exit code = %d, want %d (ExitContentSafety)", gotExit, output.ExitContentSafety)
 		}
@@ -209,7 +210,7 @@ func TestHandleRootError_SecurityPolicyCanonicalEnvelope(t *testing.T) {
 			},
 		}
 
-		gotExit := handleRootError(f, spErr, nil)
+		gotExit := handleRootError(f, spErr)
 		if gotExit != int(output.ExitContentSafety) {
 			t.Errorf("exit code = %d, want %d", gotExit, output.ExitContentSafety)
 		}
@@ -286,7 +287,7 @@ func TestHandleRootError_DeprecatedAliasMissingFlagStructured(t *testing.T) {
 	})
 	// The bare error shape cobra's ValidateRequiredFlags produces: not a typed
 	// errs.* error, so it reaches the deprecation fallback.
-	exit := handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"), nil)
+	exit := handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"))
 
 	out := errOut.String()
 	if strings.HasPrefix(strings.TrimSpace(out), "Error:") {
@@ -314,7 +315,7 @@ func TestHandleRootError_AuthConfigWireGolden(t *testing.T) {
 		errOut := &bytes.Buffer{}
 		f.IOStreams.ErrOut = errOut
 
-		exit := handleRootError(f, internalauth.NewNeedUserAuthorizationError("u_golden"), nil)
+		exit := handleRootError(f, internalauth.NewNeedUserAuthorizationError("u_golden"))
 		if exit != int(output.ExitAuth) {
 			t.Errorf("exit = %d, want %d (ExitAuth)", exit, int(output.ExitAuth))
 		}
@@ -345,7 +346,7 @@ func TestHandleRootError_AuthConfigWireGolden(t *testing.T) {
 		errOut := &bytes.Buffer{}
 		f.IOStreams.ErrOut = errOut
 
-		exit := handleRootError(f, core.NotConfiguredError(), nil)
+		exit := handleRootError(f, core.NotConfiguredError())
 		if exit != int(output.ExitAuth) {
 			t.Errorf("exit = %d, want %d (config shares ExitAuth)", exit, int(output.ExitAuth))
 		}
@@ -393,7 +394,7 @@ func TestHandleRootError_NoDeprecationTypesUsageError(t *testing.T) {
 	errOut := &bytes.Buffer{}
 	f.IOStreams.ErrOut = errOut
 
-	exit := handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"), nil)
+	exit := handleRootError(f, fmt.Errorf(`required flag(s) %q not set`, "values"))
 
 	out := errOut.String()
 	if strings.HasPrefix(strings.TrimSpace(out), "Error:") {
@@ -424,7 +425,7 @@ func TestHandleRootError_LeakedUntypedErrorBecomesInternal(t *testing.T) {
 	errOut := &bytes.Buffer{}
 	f.IOStreams.ErrOut = errOut
 
-	exit := handleRootError(f, fmt.Errorf("upstream helper exploded: %w", io.ErrUnexpectedEOF), nil)
+	exit := handleRootError(f, fmt.Errorf("upstream helper exploded: %w", io.ErrUnexpectedEOF))
 
 	errObj := decodeErrorEnvelope(t, errOut.Bytes())
 	if got := errObj["type"]; got != "internal" {
@@ -435,6 +436,25 @@ func TestHandleRootError_LeakedUntypedErrorBecomesInternal(t *testing.T) {
 	}
 }
 
+func TestHandleRootError_BlockErrorPreservesUntypedFallback(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	errOut := &bytes.Buffer{}
+	f.IOStreams.ErrOut = errOut
+	blockErr := &extcred.BlockError{Provider: "env", Reason: "LARKSUITE_CLI_APP_ID is missing"}
+
+	exit := handleRootError(f, blockErr)
+	errObj := decodeErrorEnvelope(t, errOut.Bytes())
+	if errObj["type"] != "internal" || errObj["subtype"] != "unknown" {
+		t.Fatalf("error = %#v", errObj)
+	}
+	if errObj["message"] != "blocked by env: LARKSUITE_CLI_APP_ID is missing" {
+		t.Fatalf("error.message = %v", errObj["message"])
+	}
+	if exit != int(output.ExitInternal) {
+		t.Fatalf("exit = %d, want %d", exit, output.ExitInternal)
+	}
+}
+
 // TestHandleRootError_PartialWritePreservesExitCode pins that when the
 // stderr write fails mid-envelope, handleRootError still returns the typed
 // exit code (ExitAuth=3 for AuthenticationError), not fall through to the
@@ -449,7 +469,7 @@ func TestHandleRootError_PartialWritePreservesExitCode(t *testing.T) {
 	f.IOStreams.ErrOut = w
 
 	err := errs.NewAuthenticationError(errs.SubtypeTokenExpired, "token expired")
-	exit := handleRootError(f, err, nil)
+	exit := handleRootError(f, err)
 	if exit != int(output.ExitAuth) {
 		t.Errorf("exit = %d, want %d (typed exit code preserved despite write failure)", exit, int(output.ExitAuth))
 	}
@@ -466,7 +486,7 @@ func TestHandleRootError_BareErrorExitCodeNoStderr(t *testing.T) {
 	errOut := &bytes.Buffer{}
 	f.IOStreams.ErrOut = errOut
 
-	exit := handleRootError(f, output.ErrBare(output.ExitAuth), nil)
+	exit := handleRootError(f, output.ErrBare(output.ExitAuth))
 	if exit != int(output.ExitAuth) {
 		t.Errorf("exit = %d, want %d (BareError code propagated)", exit, int(output.ExitAuth))
 	}
@@ -492,7 +512,7 @@ func TestHandleRootError_TypedAuthErrorWithLegacyCausePreserved(t *testing.T) {
 		WithHint("custom producer hint").
 		WithCause(innerLegacy)
 
-	exit := handleRootError(f, outer, nil)
+	exit := handleRootError(f, outer)
 	if exit != int(output.ExitAuth) {
 		t.Errorf("exit = %d, want %d (ExitAuth)", exit, int(output.ExitAuth))
 	}

cmd/root_upgrade.go

@@ -11,8 +11,6 @@ import (
 
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/update"
 	"github.com/spf13/cobra"
 )
 
@@ -29,8 +27,6 @@ var runRootUpgrade = func(cmd *cobra.Command) {
 	}
 }
 
-var checkRootCachedUpdate = update.CheckCached
-
 // isBareRootInvocation reports whether this is a bare `lark-cli` (no subcommand,
 // no flags) — the only invocation that triggers the interactive upgrade prompt.
 // Mirrors unknownSubcommandRunE's "bare group prints help" branch: args empty
@@ -54,20 +50,17 @@ func readYes(r io.Reader) bool {
 // offerRootUpgrade prompts for an interactive upgrade when running bare
 // `lark-cli` in an interactive terminal with a cached newer version. Every
 // failure is swallowed — it must never affect help output or the exit code.
-func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command, projector *recovery.Projector) {
-	if f == nil || !projector.CanReference(recovery.TargetUpdate) {
-		return
-	}
+func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command) {
 	ios := f.IOStreams
 	// Gates 1/2/3: need to read stdin AND show the prompt on stderr, and require
 	// stdout TTY too so this only fires in a pure foreground terminal session.
 	if !ios.IsTerminal || !ios.OutIsTerminal || !ios.StderrIsTerminal {
 		return
 	}
-	// Gate 4: cached newer version. CheckCached applies opt-out (shouldSkip)
-	// and the IsNewer/semver validation chain; it reads the on-disk cache that
-	// the 24h-throttled RefreshCache maintains (CheckCached itself has no TTL).
-	info := checkRootCachedUpdate(build.Version)
+	// Gate 4: cached newer version from this binary's release channel.
+	// Standard reads the npm-backed cache; Extended reads its separate
+	// GitHub-release cache.
+	info := checkCachedEditionUpdate(build.Version)
 	if info == nil {
 		return
 	}
@@ -82,18 +75,14 @@ func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command, projector *recover
 // unknownSubcommandRunE by installUnknownSubcommandGuard) so a bare `lark-cli`
 // invocation offers an interactive upgrade before printing help. Non-bare
 // invocations are passed straight through, unchanged.
-func installRootUpgradePrompt(
-	f *cmdutil.Factory,
-	root *cobra.Command,
-	projector *recovery.Projector,
-) {
+func installRootUpgradePrompt(f *cmdutil.Factory, root *cobra.Command) {
 	inner := root.RunE
 	if inner == nil {
 		return
 	}
 	root.RunE = func(cmd *cobra.Command, args []string) error {
 		if isBareRootInvocation(args) {
-			offerRootUpgrade(f, cmd, projector)
+			offerRootUpgrade(f, cmd)
 		}
 		return inner(cmd, args)
 	}

cmd/root_upgrade_test.go

@@ -6,7 +6,6 @@ package cmd
 import (
 	"bytes"
 	"fmt"
-	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -15,16 +14,21 @@ import (
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
-	"github.com/larksuite/cli/internal/update"
+	"github.com/larksuite/cli/internal/vfs"
 	"github.com/spf13/cobra"
 )
 
-func writeUpdateState(t *testing.T, dir, latest string) {
+func updateStateFileForEdition(edition string) string {
+	if edition == "extended" {
+		return "update-state-extended.json"
+	}
+	return "update-state.json"
+}
+
+func writeUpdateState(t *testing.T, dir, edition, latest string) {
 	t.Helper()
 	data := fmt.Sprintf(`{"latest_version":%q,"checked_at":%d}`, latest, time.Now().Unix())
-	if err := os.WriteFile(filepath.Join(dir, "update-state.json"), []byte(data), 0o644); err != nil {
+	if err := vfs.WriteFile(filepath.Join(dir, updateStateFileForEdition(edition)), []byte(data), 0o600); err != nil {
 		t.Fatal(err)
 	}
 }
@@ -108,7 +112,7 @@ func TestOfferRootUpgrade(t *testing.T) {
 			t.Setenv("RUN_ID", "")
 			t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
 			if tc.latest != "" {
-				writeUpdateState(t, dir, tc.latest)
+				writeUpdateState(t, dir, build.Edition, tc.latest)
 			}
 			if tc.optOut {
 				t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
@@ -125,7 +129,7 @@ func TestOfferRootUpgrade(t *testing.T) {
 				OutIsTerminal:    tc.out,
 				StderrIsTerminal: tc.err,
 			}}
-			offerRootUpgrade(f, &cobra.Command{}, nil)
+			offerRootUpgrade(f, &cobra.Command{})
 
 			gotPrompt := strings.Contains(errBuf.String(), "available")
 			if gotPrompt != tc.wantPrompt {
@@ -138,31 +142,50 @@ func TestOfferRootUpgrade(t *testing.T) {
 	}
 }
 
-func TestOfferRootUpgradeDoesNotReadCacheWhenUpdateIsConcealed(t *testing.T) {
-	oldCheck := checkRootCachedUpdate
-	t.Cleanup(func() { checkRootCachedUpdate = oldCheck })
+func TestOfferRootUpgradeIgnoresOtherEditionCache(t *testing.T) {
+	origV := build.Version
+	build.Version = "1.0.0"
+	t.Cleanup(func() { build.Version = origV })
 
-	cacheReads := 0
-	checkRootCachedUpdate = func(string) *update.UpdateInfo {
-		cacheReads++
-		return &update.UpdateInfo{Current: "1.0.0", Latest: "2.0.0"}
+	origRun := runRootUpgrade
+	t.Cleanup(func() { runRootUpgrade = origRun })
+
+	origWS := core.CurrentWorkspace()
+	t.Cleanup(func() { core.SetCurrentWorkspace(origWS) })
+	core.SetCurrentWorkspace(core.WorkspaceLocal)
+
+	dir := t.TempDir()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
+	t.Setenv("CI", "")
+	t.Setenv("BUILD_NUMBER", "")
+	t.Setenv("RUN_ID", "")
+	t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
+
+	otherEdition := "extended"
+	if build.Edition == "extended" {
+		otherEdition = "standard"
 	}
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandUpdate: surface.CommandConcealed,
-	})
-	projector := recovery.NewProjector(func() *surface.Plan { return plan })
+	writeUpdateState(t, dir, otherEdition, "9.0.0")
+
+	called := false
+	runRootUpgrade = func(*cobra.Command) { called = true }
+	var errBuf bytes.Buffer
 	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
 		In:               strings.NewReader("y\n"),
 		Out:              &bytes.Buffer{},
-		ErrOut:           &bytes.Buffer{},
+		ErrOut:           &errBuf,
 		IsTerminal:       true,
 		OutIsTerminal:    true,
 		StderrIsTerminal: true,
 	}}
 
-	offerRootUpgrade(f, &cobra.Command{}, projector)
-	if cacheReads != 0 {
-		t.Fatalf("concealed update read cache %d time(s)", cacheReads)
+	offerRootUpgrade(f, &cobra.Command{})
+
+	if strings.Contains(errBuf.String(), "available") {
+		t.Fatalf("%s prompt consumed %s cache: %q", build.Edition, otherEdition, errBuf.String())
+	}
+	if called {
+		t.Fatalf("%s upgrade ran from %s cache", build.Edition, otherEdition)
 	}
 }
 
@@ -178,7 +201,7 @@ func TestInstallRootUpgradePromptPreservesInner(t *testing.T) {
 	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
 		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
 	}}
-	installRootUpgradePrompt(f, root, nil)
+	installRootUpgradePrompt(f, root)
 
 	if err := root.RunE(root, []string{}); err != nil {
 		t.Fatalf("bare RunE err = %v", err)
@@ -215,7 +238,7 @@ func TestInstallRootUpgradePromptNilInnerNoop(t *testing.T) {
 	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
 		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
 	}}
-	installRootUpgradePrompt(f, root, nil)
+	installRootUpgradePrompt(f, root)
 	if root.RunE != nil {
 		t.Error("installRootUpgradePrompt must not wrap a nil RunE (inner==nil guard)")
 	}

cmd/service/affordance.go

@@ -13,7 +13,6 @@ import (
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
-	"github.com/larksuite/cli/internal/skillref"
 	"github.com/spf13/cobra"
 )
 
@@ -28,12 +27,6 @@ import (
 // we fall back to it. The pristine base is captured once into an annotation so
 // re-rendering does not append the guidance twice.
 func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
-	return PrepareDomainHelpWithReferences(cmd, skillFS, nil)
-}
-
-// PrepareDomainHelpWithReferences is PrepareDomainHelp with a build-local
-// canonical-to-runtime skill projection.
-func PrepareDomainHelpWithReferences(cmd *cobra.Command, skillFS fs.FS, references *skillref.Resolver) bool {
 	if cmd.Annotations[schemaPathAnnotation] != "" {
 		return false // a method command
 	}
@@ -68,12 +61,10 @@ func PrepareDomainHelpWithReferences(cmd *cobra.Command, skillFS fs.FS, referenc
 		b.WriteString("\n\nPrefer a +-prefixed shortcut when one matches your task; otherwise use the raw API resource below.")
 	}
 	b.WriteString("\n\nRisk levels (read | write | high-risk-write) appear in each command's --help; high-risk-write requires --yes, only after the user confirms.")
-	canonicalSkill := "lark-" + cmd.Name()
-	if declared, ok := affordance.DomainSkill(cmdmeta.Domain(cmd)); ok {
-		canonicalSkill = declared
-	}
-	if skill, ok := resolveSkillReference(canonicalSkill, skillFS, references); ok {
-		fmt.Fprintf(&b, "\n\nDomain guide (concepts, command choice, conventions): lark-cli skills read %s", skill)
+	if skill := "lark-" + cmd.Name(); skillFS != nil {
+		if _, err := fs.Stat(skillFS, skill+"/SKILL.md"); err == nil {
+			fmt.Fprintf(&b, "\n\nDomain guide (concepts, command choice, conventions): lark-cli skills read %s", skill)
+		}
 	}
 	cmd.Long = b.String()
 	return true
@@ -146,34 +137,6 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 // affordance.SkillStatPath), so a typo or a build without embedded skills never
 // prints a `skills read` that cannot be opened.
 func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
-	return PrepareMethodHelpWithReferences(cmd, skillFS, nil)
-}
-
-// PrepareMethodHelpWithReferences is PrepareMethodHelp with a build-local
-// canonical-to-runtime skill projection.
-func PrepareMethodHelpWithReferences(cmd *cobra.Command, skillFS fs.FS, references *skillref.Resolver) bool {
-	return prepareMethodHelp(cmd, skillFS, references, nil)
-}
-
-// PrepareMethodHelpWithProjection is PrepareMethodHelpWithReferences with the
-// command tree's lazy, build-local schema-reference decision. The established
-// helpers remain fully-visible by default; cmd.Build uses this form so the
-// framework-owned schema pointer follows the same surface as execution.
-func PrepareMethodHelpWithProjection(
-	cmd *cobra.Command,
-	skillFS fs.FS,
-	references *skillref.Resolver,
-	canReferenceSchema func() bool,
-) bool {
-	return prepareMethodHelp(cmd, skillFS, references, canReferenceSchema)
-}
-
-func prepareMethodHelp(
-	cmd *cobra.Command,
-	skillFS fs.FS,
-	references *skillref.Resolver,
-	canReferenceSchema func() bool,
-) bool {
 	ann := cmd.Annotations
 	if ann == nil {
 		return false
@@ -198,12 +161,10 @@ func prepareMethodHelp(
 		}
 	}
 
-	if canReferenceSchema == nil || canReferenceSchema() {
-		fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
-	}
+	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(ann[paramsOnlyAnnotation])
 
-	writeRelatedSkills(&b, skills, skillFS, references)
+	writeRelatedSkills(&b, skills, skillFS)
 
 	cmd.Long = b.String()
 	return true
@@ -216,9 +177,10 @@ func prepareMethodHelp(
 // entry, so shortcuts without guidance keep the default help plus the bottom
 // risk/tips append.
 //
-// The lead is the command's pristine base (captureHelpBase): a shortcut with a
-// hand-authored Long keeps it, while structured affordance guidance is
-// appended below without clobbering the business description.
+// The lead is the command's pristine base (captureHelpBase): a shortcut that
+// set a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST
+// read the skill" directive) keeps it — the affordance block is appended below,
+// never clobbering it.
 //
 // Tips precedence (intentional, not a bug): the overlay's ### Tips win. The
 // shortcut's declarative Tips (the Go Tips field) are only a fallback used when
@@ -226,12 +188,6 @@ func prepareMethodHelp(
 // (replaced, not merged) so tips never render twice. Authoring a ### Tips block
 // therefore silently retires that shortcut's Go Tips — consolidate into one.
 func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
-	return PrepareShortcutHelpWithReferences(cmd, skillFS, nil)
-}
-
-// PrepareShortcutHelpWithReferences is PrepareShortcutHelp with a build-local
-// canonical-to-runtime skill projection.
-func PrepareShortcutHelpWithReferences(cmd *cobra.Command, skillFS fs.FS, references *skillref.Resolver) bool {
 	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceShortcut {
 		return false
 	}
@@ -254,7 +210,7 @@ func PrepareShortcutHelpWithReferences(cmd *cobra.Command, skillFS fs.FS, refere
 		b.WriteString("\n\n")
 		b.WriteString(block)
 	}
-	writeRelatedSkills(&b, a.Skills, skillFS, references)
+	writeRelatedSkills(&b, a.Skills, skillFS)
 
 	cmd.Long = b.String()
 	return true
@@ -278,14 +234,14 @@ func writeRisk(b *strings.Builder, cmd *cobra.Command) {
 // writeRelatedSkills appends the "Related skills" block for the entries that
 // exist in skillFS. Nothing is written when skillFS is nil or no entry resolves,
 // so help never prints a `skills read` pointer that cannot be opened.
-func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS, references *skillref.Resolver) {
+func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS) {
 	if skillFS == nil || len(skills) == 0 {
 		return
 	}
 	var avail []string
 	for _, s := range skills {
-		if resolved, ok := resolveSkillReference(s, skillFS, references); ok {
-			avail = append(avail, resolved)
+		if _, err := fs.Stat(skillFS, affordance.SkillStatPath(s)); err == nil {
+			avail = append(avail, s)
 		}
 	}
 	if len(avail) == 0 {
@@ -297,22 +253,6 @@ func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS, refe
 	}
 }
 
-func resolveSkillReference(canonical string, skillFS fs.FS, references *skillref.Resolver) (string, bool) {
-	// A nil skillFS is also the command-surface gate supplied by cmd.Build:
-	// embedded bytes may still exist, but presenters must not point at them
-	// when `skills read` is concealed.
-	if skillFS == nil {
-		return "", false
-	}
-	if references != nil {
-		return references.ResolveString(canonical)
-	}
-	if _, err := fs.Stat(skillFS, affordance.SkillStatPath(canonical)); err != nil {
-		return "", false
-	}
-	return canonical, true
-}
-
 // affordanceLookup is the overlay source; a package var so tests can inject.
 var affordanceLookup = affordance.For
 

cmd/service/affordance_test.go

@@ -9,13 +9,9 @@ import (
 	"testing"
 	"testing/fstest"
 
-	"github.com/larksuite/cli/internal/affordance"
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/skillref"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/spf13/cobra"
 )
 
@@ -146,40 +142,6 @@ func TestPrepareMethodHelp(t *testing.T) {
 	}
 }
 
-func TestPrepareMethodHelpProjectsConcealedSchemaPointer(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
-		return json.RawMessage(`{"use_when":["发文本消息"]}`), true
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
-	m := map[string]interface{}{
-		"id": "messages.create", "path": "messages", "httpMethod": "POST",
-		"description": "发送消息",
-	}
-	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandSchema: surface.CommandConcealed,
-	})
-	projector := recovery.NewProjector(func() *surface.Plan { return plan })
-
-	if !PrepareMethodHelpWithProjection(cmd, nil, nil, func() bool {
-		return projector.CanReference(recovery.TargetSchema)
-	}) {
-		t.Fatal("PrepareMethodHelpWithProjection returned false for a service-method command")
-	}
-	if strings.Contains(cmd.Long, "lark-cli schema") ||
-		strings.Contains(cmd.Long, "Full parameter schema:") {
-		t.Fatalf("concealed schema left a dead method-help pointer:\n%s", cmd.Long)
-	}
-	for _, want := range []string{"发送消息", "When to use:", "发文本消息"} {
-		if !strings.Contains(cmd.Long, want) {
-			t.Errorf("schema projection removed unrelated help %q:\n%s", want, cmd.Long)
-		}
-	}
-}
-
 // PrepareShortcutHelp composes a shortcut's Long from its overlay with the same
 // top layout as method help (no schema pointer), folding declarative tips when
 // the overlay declares none, and leaves shortcuts without an overlay entry (and
@@ -271,61 +233,9 @@ func TestRelatedSkillsStatGating(t *testing.T) {
 	}
 }
 
-func TestDomainSkillReferenceRequiresReadableCommandSurface(t *testing.T) {
-	content := fstest.MapFS{
-		"lark-im/SKILL.md": {Data: []byte("# im")},
-	}
-	resolver, err := skillref.New(content, nil)
-	if err != nil {
-		t.Fatalf("skillref.New(): %v", err)
-	}
-	root := &cobra.Command{Use: "lark-cli"}
-	domain := &cobra.Command{Use: "im", Short: "IM"}
-	cmdmeta.SetSource(domain, cmdmeta.SourceService, false)
-	domain.AddCommand(&cobra.Command{Use: "messages", Run: func(*cobra.Command, []string) {}})
-	root.AddCommand(domain)
-
-	if !PrepareDomainHelpWithReferences(domain, nil, resolver) {
-		t.Fatal("PrepareDomainHelp returned false")
-	}
-	if strings.Contains(domain.Long, "skills read") {
-		t.Fatalf("concealed skills/read leaked through resolver:\n%s", domain.Long)
-	}
-}
-
-func TestDomainSkillReferenceUsesDeclaredAffordanceName(t *testing.T) {
-	affordance.SetSource(fstest.MapFS{
-		"docs.md": {Data: []byte("# docs\n> skill: lark-doc\n")},
-	})
-	t.Cleanup(func() { affordance.SetSource(nil) })
-	content := fstest.MapFS{
-		"lark-doc/SKILL.md": {Data: []byte("# docs")},
-	}
-	resolver, err := skillref.New(content, nil)
-	if err != nil {
-		t.Fatalf("skillref.New(): %v", err)
-	}
-	root := &cobra.Command{Use: "lark-cli"}
-	domain := &cobra.Command{Use: "docs", Short: "Docs"}
-	cmdmeta.SetSource(domain, cmdmeta.SourceService, false)
-	cmdmeta.SetDomain(domain, "docs")
-	domain.AddCommand(&cobra.Command{Use: "documents", Run: func(*cobra.Command, []string) {}})
-	root.AddCommand(domain)
-
-	if !PrepareDomainHelpWithReferences(domain, content, resolver) {
-		t.Fatal("PrepareDomainHelp returned false")
-	}
-	if !strings.Contains(domain.Long, "skills read lark-doc") {
-		t.Fatalf("declared domain skill was not used:\n%s", domain.Long)
-	}
-	if strings.Contains(domain.Long, "skills read lark-docs") {
-		t.Fatalf("command-name inference overrode declared domain skill:\n%s", domain.Long)
-	}
-}
-
-// A shortcut that sets a hand-authored Long keeps it as the lead: the
-// affordance block is appended below, not clobbered, and re-rendering does not
-// double-append.
+// A shortcut that set a hand-authored Long (as the docs shortcuts do in
+// PostMount) keeps it as the lead: the affordance block is appended below, not
+// clobbered, and re-rendering does not double-append.
 func TestPrepareShortcutHelp_PreservesPostMountLong(t *testing.T) {
 	orig := affordanceLookup
 	t.Cleanup(func() { affordanceLookup = orig })
@@ -387,26 +297,6 @@ func TestPrepareDomainHelp_PreservesHandAuthoredLong(t *testing.T) {
 }
 
 // A service domain carries only a Short at help time; it seeds the base.
-// The domain-guide pointer is likewise gated: removing the domain's skill
-// drops the pointer instead of leaving it dangling.
-func TestPrepareDomainHelp_GatesGuidePointerOnFS(t *testing.T) {
-	present := domainCmd("Consume and manage real-time events", "")
-	if !PrepareDomainHelp(present, fstest.MapFS{"lark-event/SKILL.md": &fstest.MapFile{Data: []byte("x")}}) {
-		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
-	}
-	if !strings.Contains(present.Long, "lark-cli skills read lark-event") {
-		t.Errorf("skill present should emit the domain-guide pointer; got:\n%s", present.Long)
-	}
-
-	removed := domainCmd("Consume and manage real-time events", "")
-	if !PrepareDomainHelp(removed, fstest.MapFS{}) {
-		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
-	}
-	if strings.Contains(removed.Long, "skills read lark-event") {
-		t.Errorf("removed skill must leave no domain-guide pointer; got:\n%s", removed.Long)
-	}
-}
-
 func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
 	dom := domainCmd("Message and group chat management", "")
 	if !PrepareDomainHelp(dom, nil) {

cmd/service/paramflags_test.go

@@ -11,8 +11,6 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
-	"github.com/larksuite/cli/internal/recovery"
-	"github.com/larksuite/cli/internal/surface"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
@@ -599,38 +597,6 @@ func TestServiceMethod_MissingRequired_HintNamesFlagAndParams(t *testing.T) {
 	}
 }
 
-func TestServiceMethod_MissingRequired_ProjectsOnlySchemaRecovery(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
-	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
-	cmd.SetArgs([]string{"--data", `{"id_list":["ou_x"]}`, "--dry-run"})
-
-	source := cmd.Execute()
-	plan := surface.NewPlan(map[surface.CommandID]surface.CommandState{
-		surface.CommandSchema: surface.CommandConcealed,
-	})
-	rendered := recovery.NewProjector(func() *surface.Plan { return plan }).Render(source)
-	var ve *errs.ValidationError
-	if !errors.As(rendered, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", rendered, rendered)
-	}
-	for _, want := range []string{"--chat-id", `--params '{"chat_id": "<value>"}'`} {
-		if !strings.Contains(ve.Hint, want) {
-			t.Errorf("projected hint %q lost valid recovery %q", ve.Hint, want)
-		}
-	}
-	if strings.Contains(ve.Hint, "lark-cli schema") {
-		t.Errorf("projected hint retained concealed schema pointer: %q", ve.Hint)
-	}
-
-	var sourceValidation *errs.ValidationError
-	if !errors.As(source, &sourceValidation) {
-		t.Fatalf("source is not *errs.ValidationError: %T", source)
-	}
-	if !strings.Contains(sourceValidation.Hint, "lark-cli schema im.chat.members.create") {
-		t.Errorf("presentation mutated source hint: %q", sourceValidation.Hint)
-	}
-}
-
 // A params-only required field (kebab name claimed by the standard --format
 // flag) has no typed flag to offer: the hint must give only the --params form,
 // never steer the reader to the colliding flag.

cmd/service/service.go

@@ -21,7 +21,6 @@ import (
 	"github.com/larksuite/cli/internal/errclass"
 	"github.com/larksuite/cli/internal/meta"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 	"github.com/larksuite/cli/internal/registry"
 	"github.com/larksuite/cli/internal/validate"
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -491,15 +490,19 @@ func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider
 
 // newPreflightMissingScopeError constructs a PermissionError for the local
 // pre-flight scope check that converges byte-for-byte with the dispatcher's
-// BuildAPIError path. It records the same typed facts and canonical message;
-// the root presenter supplies identity-appropriate recovery at the final
-// command boundary.
+// BuildAPIError path. Uses the canonical helpers in internal/errclass so
+// Hint and Message stay in lock-step with the server-response classifier.
 // ConsoleURL is deliberately omitted: the dispatcher only sets it for
 // SubtypeAppScopeNotApplied (bot-perspective dev-action recovery), and this
 // pre-flight path is user-perspective SubtypeMissingScope whose recovery is
 // `lark-cli auth login --scope ...`, not a console deep-link.
-func newPreflightMissingScopeError(brand, appID, identity string, missing []string) error {
-	return errclass.NewMissingScopeError(brand, appID, identity, missing)
+func newPreflightMissingScopeError(brand, appID, identity string, missing []string) *errs.PermissionError {
+	consoleURL := errclass.ConsoleURL(brand, appID, missing)
+	return errs.NewPermissionError(errs.SubtypeMissingScope,
+		"%s", errclass.CanonicalPermissionMessage(errs.SubtypeMissingScope, appID, missing, "")).
+		WithHint("%s", errclass.PermissionHint(missing, identity, errs.SubtypeMissingScope, consoleURL)).
+		WithMissingScopes(missing...).
+		WithIdentity(identity)
 }
 
 // unusableParamValue reports whether a provided path/query parameter value
@@ -526,28 +529,12 @@ func unusableParamValue(v interface{}) bool {
 // only the --params form: a flag with its kebab name exists but belongs to
 // something else (e.g. the output --format), and the hint must not steer
 // there. Asking the binder, not cmd.Flags(), is what tells those apart.
-func missingParamHint(opts *ServiceMethodOptions, f meta.Field) recovery.Hint {
+func missingParamHint(opts *ServiceMethodOptions, f meta.Field) string {
 	paramsForm := fmt.Sprintf("--params '{%q: \"<value>\"}'", f.Name)
-	var input string
 	if opts.binder.hasTypedFlag(f.Name) {
-		input = fmt.Sprintf("set --%s <value> (or %s)", f.FlagName(), paramsForm)
-	} else {
-		input = fmt.Sprintf("set %s", paramsForm)
+		return fmt.Sprintf("set --%s <value> (or %s); see: lark-cli schema %s", f.FlagName(), paramsForm, opts.SchemaPath)
 	}
-	return recovery.Join("; ",
-		recovery.Text(input),
-		recovery.Command(recovery.TargetSchema, "see: lark-cli schema "+opts.SchemaPath),
-	)
-}
-
-func missingRequiredParamError(opts *ServiceMethodOptions, f meta.Field, location string) error {
-	hint := missingParamHint(opts, f)
-	return recovery.Attach(
-		errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"missing required %s parameter: %s", location, f.Name).
-			WithParam(f.Name),
-		hint,
-	)
+	return fmt.Sprintf("set %s; see: lark-cli schema %s", paramsForm, opts.SchemaPath)
 }
 
 // buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
@@ -584,7 +571,10 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		}
 		val, ok := params[s.Name]
 		if !ok || unusableParamValue(val) {
-			return client.RawApiRequest{}, nil, missingRequiredParamError(opts, s, "path")
+			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"missing required path parameter: %s", s.Name).
+				WithHint("%s", missingParamHint(opts, s)).
+				WithParam(s.Name)
 		}
 		valStr := fmt.Sprintf("%v", val)
 		if err := validate.ResourceName(valStr, s.Name); err != nil {
@@ -602,7 +592,10 @@ func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmd
 		value, exists := params[s.Name]
 		isPaginationParam := opts.PageAll && (s.Name == "page_token" || s.Name == "page_size")
 		if s.Required && !isPaginationParam && (!exists || unusableParamValue(value)) {
-			return client.RawApiRequest{}, nil, missingRequiredParamError(opts, s, "query")
+			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"missing required query parameter: %s", s.Name).
+				WithHint("%s", missingParamHint(opts, s)).
+				WithParam(s.Name)
 		}
 		if exists && !unusableParamValue(value) {
 			queryParams[s.Name] = value

cmd/service/service_test.go

@@ -54,30 +54,6 @@ func driveMethod(httpMethod string, params map[string]interface{}) meta.Method {
 	return meta.FromMap(m)
 }
 
-func TestNewPreflightMissingScopeErrorUsesCanonicalFieldGate(t *testing.T) {
-	err := newPreflightMissingScopeError(
-		"feishu",
-		"cli_test",
-		"user",
-		[]string{"docx:document"},
-	)
-	var permissionErr *errs.PermissionError
-	if !errors.As(err, &permissionErr) {
-		t.Fatalf("error = %T, want *errs.PermissionError", err)
-	}
-	if permissionErr.Subtype != errs.SubtypeMissingScope {
-		t.Fatalf("subtype = %q, want %q", permissionErr.Subtype, errs.SubtypeMissingScope)
-	}
-	if permissionErr.ConsoleURL != "" {
-		t.Fatalf("missing_scope console_url = %q, want empty", permissionErr.ConsoleURL)
-	}
-	if len(permissionErr.MissingScopes) != 1 ||
-		permissionErr.MissingScopes[0] != "docx:document" ||
-		permissionErr.Identity != "user" {
-		t.Fatalf("permission facts = %+v", permissionErr)
-	}
-}
-
 // ── registerService ──
 
 func TestRegisterService(t *testing.T) {

cmd/skill_customization_test.go

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

cmd/startup_brand.go

@@ -10,17 +10,34 @@ import (
 	"github.com/larksuite/cli/internal/envvars"
 )
 
+// selectInvocationWorkspace establishes the workspace before any startup
+// consumer reads workspace-scoped configuration. Execute needs this before
+// resolving the registry brand, while Build/buildInternal needs it before
+// capturing the immutable Profile snapshot passed to the Factory.
+func selectInvocationWorkspace() core.Workspace {
+	workspace := core.DetectWorkspaceFromEnv(os.Getenv)
+	core.SetCurrentWorkspace(workspace)
+	return workspace
+}
+
 // ResolveStartupBrand resolves the brand before the command tree is built, so
 // the registry's remote metadata overlay uses the configured brand from the
 // first catalog access. It mirrors the credential chain's brand precedence —
 // environment, then the active profile's raw config entry — without touching
 // the keychain (no secrets are needed to know the brand).
 func ResolveStartupBrand(profile string) core.LarkBrand {
+	config, _ := core.LoadMultiAppConfig()
+	return resolveStartupBrandFromConfig(profile, config)
+}
+
+// resolveStartupBrandFromConfig keeps registry routing on the same immutable
+// Profile snapshot used by credentials and runtime policy.
+func resolveStartupBrandFromConfig(profile string, config *core.MultiAppConfig) core.LarkBrand {
 	if raw := os.Getenv(envvars.CliBrand); raw != "" {
 		return core.ParseBrand(raw)
 	}
-	if cfg, err := core.LoadMultiAppConfig(); err == nil {
-		if app := cfg.CurrentAppConfig(profile); app != nil {
+	if config != nil {
+		if app := config.CurrentAppConfig(profile); app != nil {
 			return core.ParseBrand(string(app.Brand))
 		}
 	}

cmd/update/edition_extended.go

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package cmdupdate
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/extendedupdate"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/skillscheck"
+	"github.com/larksuite/cli/internal/update"
+)
+
+var (
+	fetchExtendedLatest = extendedupdate.FetchLatest
+	installExtended     = extendedupdate.Install
+)
+
+func updateLongDescription() string {
+	return `Update lark-cli Extended from the matching GitHub Release.
+
+The command downloads the lark-cli-extended asset for the current platform,
+verifies its SHA-256 checksum and compiled edition identity, then replaces the
+current binary. It never installs the Standard npm/npx edition.
+
+Use --json for structured output (for AI agents and scripts).
+Use --check to only check for updates without installing.`
+}
+
+func runEditionUpdate(opts *UpdateOptions) (bool, error) {
+	io := opts.Factory.IOStreams
+	cur := currentVersion()
+	updater := newUpdater()
+	if !opts.Check {
+		updater.Brand = resolveSkillsBrand(opts.Factory, io.ErrOut)
+		updater.CleanupStaleFiles()
+	}
+	output.PendingNotice = nil
+
+	latest, err := fetchExtendedLatest()
+	if err != nil {
+		var typed errs.TypedError
+		if errors.As(err, &typed) {
+			return true, reportError(opts, io, "network", typed)
+		}
+		return true, reportError(opts, io, "network",
+			errs.NewNetworkError(errs.SubtypeNetworkTransport,
+				"failed to check the latest Extended version: %v", err).WithCause(err))
+	}
+	if update.ParseVersion(latest) == nil {
+		return true, reportError(opts, io, "update_error",
+			errs.NewInternalError(errs.SubtypeInvalidResponse,
+				"invalid Extended version from GitHub Releases: %s", latest))
+	}
+	if !opts.Force && !update.IsNewer(latest, cur) {
+		var skillsResult *skillscheck.SyncResult
+		if !opts.Check {
+			skillsResult = runSkillsAndState(updater, io, cur, opts.Force)
+		}
+		return true, reportAlreadyUpToDate(opts, io, cur, latest, skillsResult, opts.Check)
+	}
+	if opts.Check {
+		return true, reportCheckResult(opts, io, cur, latest, true)
+	}
+	if !opts.JSON {
+		fmt.Fprintf(io.ErrOut, "Updating lark-cli Extended %s %s %s from GitHub Releases ...\n", cur, symArrow(), latest)
+	}
+	if err := installExtended(latest); err != nil {
+		var typed errs.TypedError
+		if errors.As(err, &typed) {
+			return true, reportError(opts, io, "update_error", typed)
+		}
+		return true, reportError(opts, io, "update_error",
+			errs.NewInternalError(errs.SubtypeUnknown,
+				"failed to install lark-cli Extended: %v", err).WithCause(err))
+	}
+
+	skillsResult := runSkillsAndState(updater, io, latest, opts.Force)
+	if opts.JSON {
+		result := map[string]interface{}{
+			"ok": true, "previous_version": cur, "current_version": latest,
+			"latest_version": latest, "edition": build.Edition, "action": "updated",
+			"message": fmt.Sprintf("lark-cli Extended updated from %s to %s", cur, latest),
+			"url":     releaseURL(latest), "changelog": changelogURL(),
+		}
+		applySkillsResult(result, skillsResult)
+		output.PrintJson(io.Out, result)
+		return true, nil
+	}
+	fmt.Fprintf(io.ErrOut, "\n%s Successfully updated lark-cli Extended from %s to %s\n", symOK(), cur, latest)
+	fmt.Fprintf(io.ErrOut, "  Changelog: %s\n", changelogURL())
+	emitSkillsTextHints(io, skillsResult)
+	return true, nil
+}

cmd/update/edition_extended_test.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package cmdupdate
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/selfupdate"
+	"github.com/larksuite/cli/internal/skillscheck"
+)
+
+func TestExtendedUpdateUsesExtendedReleaseInstaller(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	oldFetch, oldInstall := fetchExtendedLatest, installExtended
+	oldVersion, oldUpdater, oldSync := currentVersion, newUpdater, syncSkills
+	t.Cleanup(func() {
+		fetchExtendedLatest, installExtended = oldFetch, oldInstall
+		currentVersion, newUpdater, syncSkills = oldVersion, oldUpdater, oldSync
+	})
+	fetchExtendedLatest = func() (string, error) { return "1.2.4", nil }
+	currentVersion = func() string { return "1.2.3" }
+	installed := ""
+	installExtended = func(version string) error {
+		installed = version
+		return nil
+	}
+	newUpdater = func() *selfupdate.Updater {
+		return &selfupdate.Updater{DetectOverride: func() selfupdate.DetectResult {
+			return selfupdate.DetectResult{Method: selfupdate.InstallManual}
+		}}
+	}
+	syncSkills = func(skillscheck.SyncOptions) *skillscheck.SyncResult { return &skillscheck.SyncResult{} }
+
+	var out, errOut bytes.Buffer
+	f := cmdutil.NewDefault(cmdutil.NewIOStreams(nil, &out, &errOut), cmdutil.InvocationContext{})
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json"})
+	if err := cmd.ExecuteContext(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if installed != "1.2.4" {
+		t.Fatalf("installed version = %q, want 1.2.4", installed)
+	}
+	var result map[string]interface{}
+	if err := json.Unmarshal(out.Bytes(), &result); err != nil {
+		t.Fatal(err)
+	}
+	if result["edition"] != "extended" || result["action"] != "updated" {
+		t.Fatalf("result = %#v", result)
+	}
+}
+
+func TestExtendedUpdateCheckDoesNotInstall(t *testing.T) {
+	oldFetch, oldInstall := fetchExtendedLatest, installExtended
+	oldVersion := currentVersion
+	t.Cleanup(func() {
+		fetchExtendedLatest, installExtended = oldFetch, oldInstall
+		currentVersion = oldVersion
+	})
+	fetchExtendedLatest = func() (string, error) { return "1.2.4", nil }
+	currentVersion = func() string { return "1.2.3" }
+	installExtended = func(string) error {
+		t.Fatal("installer called during --check")
+		return nil
+	}
+	var out bytes.Buffer
+	f := cmdutil.NewDefault(cmdutil.NewIOStreams(nil, &out, &bytes.Buffer{}), cmdutil.InvocationContext{})
+	cmd := NewCmdUpdate(f)
+	cmd.SetArgs([]string{"--json", "--check"})
+	if err := cmd.ExecuteContext(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}

cmd/update/edition_standard.go

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package cmdupdate
+
+func runEditionUpdate(*UpdateOptions) (bool, error) { return false, nil }
+
+func updateLongDescription() string {
+	return `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>
+  - manual/other: shows GitHub Releases download URL
+
+Use --json for structured output (for AI agents and scripts).
+Use --check to only check for updates without installing.`
+}

cmd/update/update.go

@@ -101,15 +101,7 @@ func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update",
 		Short: "Update lark-cli to the latest version",
-		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>
-  - manual/other: shows GitHub Releases download URL
-
-Use --json for structured output (for AI agents and scripts).
-Use --check to only check for updates without installing.`,
+		Long:  updateLongDescription(),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return updateRun(opts)
 		},
@@ -124,6 +116,9 @@ Use --check to only check for updates without installing.`,
 }
 
 func updateRun(opts *UpdateOptions) error {
+	if handled, err := runEditionUpdate(opts); handled {
+		return err
+	}
 	io := opts.Factory.IOStreams
 	cur := currentVersion()
 	updater := newUpdater()

cmd/update/update_test.go

@@ -1,6 +1,8 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
+//go:build !extended
+
 package cmdupdate
 
 import (

cmd/update_notice_extended.go

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package cmd
+
+import (
+	"github.com/larksuite/cli/internal/extendedupdate"
+	"github.com/larksuite/cli/internal/update"
+)
+
+func checkCachedEditionUpdate(currentVersion string) *update.UpdateInfo {
+	return extendedupdate.CheckCached(currentVersion)
+}
+
+func refreshEditionUpdateCache(currentVersion string) {
+	extendedupdate.RefreshCache(currentVersion)
+}

cmd/update_notice_standard.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package cmd
+
+import "github.com/larksuite/cli/internal/update"
+
+func checkCachedEditionUpdate(currentVersion string) *update.UpdateInfo {
+	return update.CheckCached(currentVersion)
+}
+
+func refreshEditionUpdateCache(currentVersion string) {
+	update.RefreshCache(currentVersion)
+}

cmd/version/version.go

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package version
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+type options struct {
+	factory *cmdutil.Factory
+	json    bool
+}
+
+type versionReport struct {
+	Version      string   `json:"version"`
+	Edition      string   `json:"edition"`
+	Capabilities []string `json:"capabilities"`
+}
+
+// NewCmdVersion reports the immutable edition identity compiled into the
+// binary. Root --version remains unchanged for compatibility.
+func NewCmdVersion(f *cmdutil.Factory) *cobra.Command {
+	opts := &options{factory: f}
+	cmd := &cobra.Command{
+		Use:    "version",
+		Short:  "Show version and edition information",
+		Hidden: hideVersionCommand(),
+		Args:   cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if opts.json {
+				output.PrintJson(opts.factory.IOStreams.Out, versionReport{
+					Version:      build.Version,
+					Edition:      build.Edition,
+					Capabilities: build.Capabilities(),
+				})
+				return nil
+			}
+			_, err := fmt.Fprintf(opts.factory.IOStreams.Out, "lark-cli version %s (%s)\n", build.Version, build.Edition)
+			if err != nil {
+				return errs.NewInternalError(errs.SubtypeSDKError, "failed to write version output: %v", err).WithCause(err)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().BoolVar(&opts.json, "json", false, "structured JSON output")
+	cmdutil.DisableAuthCheck(cmd)
+	cmdutil.SetRisk(cmd, "read")
+	return cmd
+}

cmd/version/version_test.go

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package version
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdutil"
+)
+
+func TestVersionJSONReportsCompiledEdition(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, out, _, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdVersion(f)
+	cmd.SetArgs([]string{"--json"})
+	if err := cmd.ExecuteContext(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	var got struct {
+		Version      string   `json:"version"`
+		Edition      string   `json:"edition"`
+		Capabilities []string `json:"capabilities"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Version != build.Version || got.Edition != build.Edition || !reflect.DeepEqual(got.Capabilities, build.Capabilities()) {
+		t.Fatalf("version output = %#v, want version=%q edition=%q", got, build.Version, build.Edition)
+	}
+}
+
+func TestVersionVisibilityPreservesStandardHelpSurface(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdVersion(f)
+	wantHidden := build.Edition == "standard"
+	if cmd.Hidden != wantHidden {
+		t.Fatalf("version command hidden = %v, want %v for %s", cmd.Hidden, wantHidden, build.Edition)
+	}
+}
+
+type failingWriter struct{ err error }
+
+func (w failingWriter) Write([]byte) (int, error) { return 0, w.err }
+
+func TestVersionTextWriteFailureIsTyped(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	writeErr := errors.New("write failed")
+	f.IOStreams.Out = failingWriter{err: writeErr}
+
+	cmd := NewCmdVersion(f)
+	err := cmd.ExecuteContext(context.Background())
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeSDKError {
+		t.Fatalf("error = %#v, want internal/sdk_error", err)
+	}
+	if !errors.Is(err, writeErr) {
+		t.Fatalf("error does not preserve write failure: %v", err)
+	}
+}

cmd/version/visibility_extended.go

@@ -0,0 +1,8 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build extended
+
+package version
+
+func hideVersionCommand() bool { return false }

cmd/version/visibility_standard.go

@@ -0,0 +1,10 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+//go:build !extended
+
+package version
+
+// Standard keeps its historical help surface unchanged. The command remains
+// directly callable for release identity verification.
+func hideVersionCommand() bool { return true }

cmd/whoami/whoami.go

@@ -12,7 +12,6 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
 	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/recovery"
 )
 
 // whoamiResult is the structured output of `lark-cli whoami`.
@@ -55,22 +54,12 @@ type Options struct {
 // local-only; when an external credential provider manages tokens, resolving
 // the identity may contact that provider.
 func NewCmdWhoami(f *cmdutil.Factory) *cobra.Command {
-	return newCmdWhoami(f, nil)
-}
-
-// NewCmdWhoamiWithRecovery creates whoami with a build-local recovery
-// presenter while preserving NewCmdWhoami's established function signature.
-func NewCmdWhoamiWithRecovery(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
-	return newCmdWhoami(f, projector)
-}
-
-func newCmdWhoami(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Command {
 	opts := &Options{Factory: f}
 	cmd := &cobra.Command{
 		Use:   "whoami",
 		Short: "Show the current effective identity, app, profile, and token status (JSON)",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return whoamiRun(cmd, opts, projector)
+			return whoamiRun(cmd, opts)
 		},
 	}
 	cmdutil.DisableAuthCheck(cmd)
@@ -84,7 +73,7 @@ func newCmdWhoami(f *cmdutil.Factory, projector *recovery.Projector) *cobra.Comm
 	return cmd
 }
 
-func whoamiRun(cmd *cobra.Command, opts *Options, projector *recovery.Projector) error {
+func whoamiRun(cmd *cobra.Command, opts *Options) error {
 	f := opts.Factory
 	cfg, err := f.Config()
 	if err != nil {
@@ -107,10 +96,7 @@ func whoamiRun(cmd *cobra.Command, opts *Options, projector *recovery.Projector)
 		f.IdentityAutoDetected,
 		f.ResolveStrictMode(ctx).ForcedIdentity(),
 	)
-	diag := identitydiag.FilterRecovery(
-		identitydiag.Diagnose(ctx, f, cfg, false),
-		projector.CanReference,
-	)
+	diag := identitydiag.Diagnose(ctx, f, cfg, false)
 	res := buildResult(cfg, as, source, diag)
 	output.PrintJson(f.IOStreams.Out, res)
 	return nil