refactor(auth): make keysigner internal

Drop the sks_signer build tag, mirroring the darwin keychain signer: the
TPM signer now compiles into every linux and windows/amd64 build via
constraint //go:build linux || (windows && amd64) — no -tags needed.
windows/arm64 is arch-excluded (go-ole has no arm64 VARIANT) and falls
back to client_secret only.

- goreleaser: drop -tags=sks_signer; merge windows-arm64 into the windows
  build (amd64+arm64) since no tag is needed and arm64 is arch-excluded.
- build-pkg-pr-new.sh: remove tag logic.
- doctor: update the no-signer hint (signer ships by default on macOS,
  Linux, Windows/amd64).
- Switching from a custom tag to GOOS/GOARCH constraints also lets
  go mod tidy track sks/go-tpm/go-ole correctly.

.github/workflows/ci.yml

@@ -5,7 +5,6 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
-    types: [opened, synchronize, reopened, edited]
   workflow_dispatch:
 
 permissions:
@@ -71,7 +70,6 @@ jobs:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
         with:
           fetch-depth: 0
-          persist-credentials: false
       - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version-file: go.mod
@@ -89,23 +87,6 @@ jobs:
       - name: Run errs/ lint guards (lintcheck)
         run: go run -C lint . --changed-from "$QUALITY_GATE_CHANGED_FROM" ..
 
-  script-test:
-    needs: fast-gate
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-        with:
-          fetch-depth: 0
-          persist-credentials: false
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: '22'
-      - name: Run script tests
-        run: make script-test
-
   deterministic-gate:
     needs: fast-gate
     runs-on: ubuntu-latest
@@ -128,28 +109,8 @@ jobs:
         env:
           QUALITY_GATE_CHANGED_FROM: ${{ github.event.pull_request.base.sha || github.event.before || 'origin/main' }}
         run: echo "QUALITY_GATE_CHANGED_FROM=$(bash scripts/resolve-changed-from.sh)" >> "$GITHUB_ENV"
-      - name: Write public content metadata
-        if: ${{ github.event_name == 'pull_request' }}
-        env:
-          PR_TITLE: ${{ github.event.pull_request.title }}
-          PR_BODY: ${{ github.event.pull_request.body }}
-          PR_BRANCH: ${{ github.head_ref }}
-        run: |
-          mkdir -p .tmp/quality-gate
-          python3 - <<'PY'
-          import json
-          import os
-
-          with open(".tmp/quality-gate/public-content-metadata.json", "w", encoding="utf-8") as f:
-              json.dump({
-                  "title": os.environ.get("PR_TITLE", ""),
-                  "body": os.environ.get("PR_BODY", ""),
-                  "branch": os.environ.get("PR_BRANCH", ""),
-              }, f)
-              f.write("\n")
-          PY
       - name: Run CLI deterministic gate
-        run: PUBLIC_CONTENT_METADATA=.tmp/quality-gate/public-content-metadata.json make quality-gate
+        run: make quality-gate
       - name: Upload quality gate facts
         if: ${{ always() && github.event_name == 'pull_request' }}
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
@@ -259,7 +220,7 @@ jobs:
 
   # ── Layer 3: E2E Gate ──────────────────────────────────────────────
   e2e-dry-run:
-    needs: [unit-test, lint, script-test, deterministic-gate]
+    needs: [unit-test, lint, deterministic-gate]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
@@ -280,7 +241,7 @@ jobs:
         run: go test -v -count=1 -timeout=5m ./tests/cli_e2e/... -run 'DryRun|Regression'
 
   e2e-live:
-    needs: [unit-test, lint, script-test, deterministic-gate]
+    needs: [unit-test, lint, deterministic-gate]
     if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork }}
     runs-on: ubuntu-latest
     permissions:
@@ -372,7 +333,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]
+    needs: [fast-gate, unit-test, lint, deterministic-gate, coverage, deadcode, e2e-dry-run, e2e-live, security, license-header]
     runs-on: ubuntu-latest
     steps:
       - name: Evaluate results
@@ -384,7 +345,6 @@ jobs:
           echo "| L1 | fast-gate | ${{ needs.fast-gate.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L2 | unit-test | ${{ needs.unit-test.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L2 | lint | ${{ needs.lint.result }} |" >> $GITHUB_STEP_SUMMARY
-          echo "| L2 | script-test | ${{ needs.script-test.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L2 | deterministic-gate | ${{ needs.deterministic-gate.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L2 | coverage | ${{ needs.coverage.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| L2 | deadcode | ${{ needs.deadcode.result }} |" >> $GITHUB_STEP_SUMMARY
@@ -401,7 +361,6 @@ jobs:
             "${{ needs.fast-gate.result }}" \
             "${{ needs.unit-test.result }}" \
             "${{ needs.lint.result }}" \
-            "${{ needs.script-test.result }}" \
             "${{ needs.deterministic-gate.result }}" \
             "${{ needs.coverage.result }}" \
             "${{ needs.deadcode.result }}" \

.github/workflows/comment-audit.yml

@@ -1,28 +0,0 @@
-name: Comment Audit
-
-on:
-  issue_comment:
-    types: [created, edited]
-  pull_request_review:
-    types: [submitted, edited]
-  pull_request_review_comment:
-    types: [created, edited]
-
-permissions:
-  contents: read
-
-jobs:
-  public-content-comment-audit:
-    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
-      - name: Post-publication comment audit
-        run: |
-          mkdir -p .tmp/comment-audit
-          cp "$GITHUB_EVENT_PATH" .tmp/comment-audit/event.json
-          go run ./internal/qualitygate/cmd/comment-audit --event .tmp/comment-audit/event.json --kind "$GITHUB_EVENT_NAME"

.github/workflows/release.yml

@@ -9,7 +9,11 @@ permissions:
   contents: read
 
 jobs:
+  # All platforms (incl. darwin keychain_signer) are CGO-free and cross-compiled
+  # on a single ubuntu runner in one goreleaser run (one checksums.txt). The
+  # darwin signer's runtime FFI is validated separately by the signer-test job.
   goreleaser:
+    needs: signer-test-macos
     runs-on: ubuntu-22.04
     permissions:
       contents: write
@@ -34,6 +38,21 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+  # Validate the macOS keychain signer on real hardware. The release binaries are
+  # cross-compiled on ubuntu (CGO-free purego FFI), so this is the only step that
+  # needs a Mac — and it gates the release rather than producing it.
+  signer-test-macos:
+    runs-on: macos-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version: '1.23'
+      - name: Keychain signer round-trip (CGO-free purego FFI)
+        run: LARK_KEYCHAIN_IT=1 CGO_ENABLED=0 go test -tags keychain_signer -run Keychain -v ./internal/keysigner/
+
   publish-npm:
     needs: goreleaser
     runs-on: ubuntu-22.04

.github/workflows/semantic-review.yml

@@ -47,13 +47,10 @@ jobs:
               throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
             }
             let prNumber = Number(runPRs[0]?.number || 0);
-            const eventBaseSha = runPRs[0]?.base?.sha || "";
+            let eventBaseSha = runPRs[0]?.base?.sha || "";
             const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = run.head_sha;
+            const targetHeadSha = eventHeadSha || run.head_sha;
             if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
-            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-              core.notice("PR quality summary using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
-            }
 
             const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
             const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
@@ -74,11 +71,11 @@ jobs:
               if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
                 artifactError = "facts artifact head sha does not match verified PR head sha";
                 factsArtifactName = "";
+              } else if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
+                artifactError = "facts artifact base sha does not match workflow_run pull request base sha";
+                factsArtifactName = "";
               } else {
                 artifactBaseSha = parsedBaseSha;
-                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                  core.notice("PR quality summary using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
-                }
               }
             }
             if (!prNumber) {
@@ -88,44 +85,31 @@ jobs:
                 commit_sha: targetHeadSha,
               });
               const candidatePRs = associatedPRs.filter((candidate) =>
+                candidate.state === "open" &&
                 candidate.base?.repo?.id === context.payload.repository.id &&
                 candidate.head?.sha === targetHeadSha
               );
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
+              if (candidatePRs.length > 1) {
+                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${candidatePRs.length}`);
               }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
+              if (candidatePRs.length === 1) {
+                prNumber = candidatePRs[0].number;
               }
             }
             if (!prNumber) {
               const candidatePRs = await github.paginate(github.rest.pulls.list, {
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                state: "all",
+                state: "open",
                 per_page: 100,
               }).then((prs) => prs.filter((candidate) =>
                 candidate.base?.repo?.id === context.payload.repository.id &&
                 candidate.head?.sha === targetHeadSha
               ));
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs from pull list fallback for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              } else {
+              if (candidatePRs.length !== 1) {
                 throw new Error(`expected one open PR from pull list fallback for workflow_run head ${targetHeadSha}, got ${candidatePRs.length}`);
               }
+              prNumber = candidatePRs[0].number;
             }
             if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("missing pull request binding");
             const { data: pr } = await github.rest.pulls.get({
@@ -134,17 +118,12 @@ jobs:
               pull_number: prNumber,
             });
             if (pr.base.repo.id !== context.payload.repository.id) throw new Error("PR base repo mismatch");
-            if (pr.state !== "open") {
-              core.notice("PR quality summary skipped: workflow_run target PR is no longer open");
-              core.setOutput("stale", "true");
-              return;
-            }
             if (pr.head.sha !== targetHeadSha) {
               core.notice("PR quality summary skipped: workflow_run is stale for this PR head");
               core.setOutput("stale", "true");
               return;
             }
-            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
+            const baseSha = eventBaseSha || artifactBaseSha || pr.base.sha;
             if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
             if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
               core.notice("PR quality summary skipped: workflow_run is stale for this PR base");
@@ -276,13 +255,10 @@ jobs:
               throw new Error(`ambiguous workflow_run pull request bindings: ${runPRs.length}`);
             }
             let prNumber = Number(runPRs[0]?.number || 0);
-            const eventBaseSha = runPRs[0]?.base?.sha || "";
+            let eventBaseSha = runPRs[0]?.base?.sha || "";
             const eventHeadSha = runPRs[0]?.head?.sha || "";
-            const targetHeadSha = run.head_sha;
+            const targetHeadSha = eventHeadSha || run.head_sha;
             if (!/^[a-f0-9]{40}$/i.test(targetHeadSha)) throw new Error("invalid PR head sha");
-            if (eventHeadSha && eventHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
-              core.notice("semantic review using workflow_run head_sha because workflow_run pull request head differs from the CI run head");
-            }
 
             const factsArtifactPattern = /^quality-gate-facts-([a-f0-9]{40})-([a-f0-9]{40})$/i;
             const { data: artifactData } = await github.rest.actions.listWorkflowRunArtifacts({
@@ -303,11 +279,11 @@ jobs:
               if (artifactHeadSha.toLowerCase() !== targetHeadSha.toLowerCase()) {
                 artifactError = "facts artifact head sha does not match verified PR head sha";
                 factsArtifactName = "";
+              } else if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
+                artifactError = "facts artifact base sha does not match workflow_run pull request base sha";
+                factsArtifactName = "";
               } else {
                 artifactBaseSha = parsedBaseSha;
-                if (eventBaseSha && parsedBaseSha.toLowerCase() !== eventBaseSha.toLowerCase()) {
-                  core.notice("semantic review using facts artifact base because workflow_run pull request base differs from the CI facts artifact base");
-                }
               }
             }
             if (!prNumber) {
@@ -317,44 +293,31 @@ jobs:
                 commit_sha: targetHeadSha,
               });
               const candidatePRs = associatedPRs.filter((candidate) =>
+                candidate.state === "open" &&
                 candidate.base?.repo?.id === context.payload.repository.id &&
                 candidate.head?.sha === targetHeadSha
               );
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
+              if (candidatePRs.length > 1) {
+                throw new Error(`ambiguous open PRs for workflow_run head ${targetHeadSha}: ${candidatePRs.length}`);
               }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("semantic review skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
+              if (candidatePRs.length === 1) {
+                prNumber = candidatePRs[0].number;
               }
             }
             if (!prNumber) {
               const candidatePRs = await github.paginate(github.rest.pulls.list, {
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                state: "all",
+                state: "open",
                 per_page: 100,
               }).then((prs) => prs.filter((candidate) =>
                 candidate.base?.repo?.id === context.payload.repository.id &&
                 candidate.head?.sha === targetHeadSha
               ));
-              const openCandidatePRs = candidatePRs.filter((candidate) => candidate.state === "open");
-              if (openCandidatePRs.length > 1) {
-                throw new Error(`ambiguous open PRs from pull list fallback for workflow_run head ${targetHeadSha}: ${openCandidatePRs.length}`);
-              }
-              if (openCandidatePRs.length === 1) {
-                prNumber = openCandidatePRs[0].number;
-              } else if (candidatePRs.length > 0) {
-                core.notice("semantic review skipped: workflow_run target PR is no longer open");
-                core.setOutput("stale", "true");
-                return;
-              } else {
+              if (candidatePRs.length !== 1) {
                 throw new Error(`expected one open PR from pull list fallback for workflow_run head ${targetHeadSha}, got ${candidatePRs.length}`);
               }
+              prNumber = candidatePRs[0].number;
             }
             if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("missing pull request binding");
             const { data: pr } = await github.rest.pulls.get({
@@ -363,22 +326,12 @@ jobs:
               pull_number: prNumber,
             });
             if (pr.base.repo.id !== context.payload.repository.id) throw new Error("PR base repo mismatch");
-            if (pr.state !== "open") {
-              core.notice("semantic review skipped: workflow_run target PR is no longer open");
-              core.setOutput("stale", "true");
-              return;
-            }
-            if (!pr.head.repo) {
-              core.notice("semantic review skipped: workflow_run target PR head repository is unavailable");
-              core.setOutput("stale", "true");
-              return;
-            }
             if (pr.head.sha !== targetHeadSha) {
               core.notice("semantic review skipped: workflow_run is stale for this PR head");
               core.setOutput("stale", "true");
               return;
             }
-            const baseSha = artifactBaseSha || eventBaseSha || pr.base.sha;
+            const baseSha = eventBaseSha || artifactBaseSha || pr.base.sha;
             if (!/^[a-f0-9]{40}$/i.test(baseSha)) throw new Error("invalid PR base sha");
             if ((eventBaseSha || artifactBaseSha) && pr.base.sha !== baseSha) {
               core.notice("semantic review skipped: workflow_run is stale for this PR base");
@@ -430,10 +383,6 @@ jobs:
               repo: context.repo.repo,
               pull_number: pr,
             });
-            if (pull.state !== "open") {
-              core.notice("semantic review skipped infrastructure failure check: PR is no longer open");
-              return;
-            }
             if (pull.head.sha !== headSha) {
               core.notice("semantic review skipped infrastructure failure check: PR head changed");
               return;

.gitignore

@@ -7,11 +7,6 @@ bin/
 # Node
 node_modules/
 
-# Python (skill-bundled helper scripts)
-__pycache__/
-*.py[cod]
-*$py.class
-
 
 # OS
 .DS_Store
@@ -51,4 +46,3 @@ app.log
 cover*.out
 
 lark-env.sh
-/automations/

.goreleaser.yml

@@ -5,15 +5,53 @@ before:
     - python3 scripts/fetch_meta.py
 
 builds:
-  - binary: lark-cli
+  # Linux & Windows: pure-Go TPM 2.0 signer is compiled in by default (no build
+  # tag), cross-compiled with CGO disabled — the binaries ship the platform key
+  # signer for private_key_jwt. windows/arm64 is the one exception: the sks
+  # Windows dependency stack (go-ole) has no arm64 support, so the signer file is
+  # arch-excluded there and that binary falls back to client_secret only.
+  - id: linux
+    binary: lark-cli
+    main: .
     env:
       - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
+    goos:
+      - linux
+    goarch:
+      - amd64
+      - arm64
+  - id: windows
+    binary: lark-cli
+    main: .
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -s -w -X github.com/larksuite/cli/internal/build.Version={{ .Version }} -X github.com/larksuite/cli/internal/build.Date={{ .Date }}
+    goos:
+      - windows
+    goarch:
+      - amd64
+      - arm64
+  # macOS: the keychain signer calls Security.framework via runtime FFI (purego),
+  # so it is CGO-free, compiled into every darwin build (no build tag), and
+  # cross-compiles from the same ubuntu runner as linux/windows.
+  - id: darwin
+    binary: lark-cli
+    main: .
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
     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
@@ -23,7 +61,7 @@ archives:
   - name_template: "lark-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
     format_overrides:
       - goos: windows
-        format: zip
+        formats: [zip]
     files:
       - README.md
       - LICENSE

CHANGELOG.md

@@ -2,127 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.62] - 2026-07-01
-
-### Features
-
-- **vc**: Add meeting message send shortcut (#1643)
-- **doc**: Add document word statistics helper (#1697)
-- **cli**: Interactive upgrade prompt for bare `lark-cli` invocation (#1498)
-- **install**: Fail closed when `checksums.txt` is missing during install (#1503)
-
-### Bug Fixes
-
-- **drive**: Improve batch failure handling for push/pull/sync (#1703)
-- **base**: Support JSON array input for field create (#1661)
-- **task**: Expose completion state in `my tasks` output (#1641)
-- **cli**: Reduce public content credential false positives (#1700)
-
-## [v1.0.61] - 2026-06-30
-
-### Features
-
-- **apps**: Add `db`, `file`, `openapi-key` and observability shortcuts (#1596)
-- **identity**: Add `whoami` command showing effective identity (#1666)
-- **docs**: Add reference map flags (#1547)
-
-### Bug Fixes
-
-- **identity**: Correct identity diagnosis under external credential providers (#1693)
-- **cli**: Harden git credential error handling (#1676)
-
-### Documentation
-
-- **doc**: Guide document copy skill usage (#1673)
-- **doc**: Fix lark-doc media token examples (#1662)
-
-## [v1.0.60] - 2026-06-29
-
-### Features
-
-- **affordance**: Per-command usage guidance system with markdown source (#1565)
-- **event**: Support VC meeting lifecycle events (#1632)
-- **sheets**: Use `office_sheet_file` parent_type for imported office spreadsheets (#1606)
-- **authorization**: Expand lark-shared auth guidance and assert clean logout JSON (#1598)
-- **transport**: Add `LARK_CLI_NO_PROXY_WARN` to silence proxy warning (#1647)
-
-### Bug Fixes
-
-- **install**: Load `@clack/prompts` via dynamic import to avoid `ERR_REQUIRE_ESM` (#1652)
-
-### Tests
-
-- **doc**: Derive fetch test flag defaults from `v2FetchFlags` (#1428)
-
-### Build
-
-- **ci**: Reduce public content false positives
-
-## [v1.0.59] - 2026-06-26
-
-### Features
-
-- **slides**: Add `+replace-pages` and `xml get` shortcuts, and expose the presentation URL (#1585)
-- **minutes**: Support speaker list and no-Lark speaker replace (#1594)
-- **calendar/vc/minutes**: Optimize and extend calendar, vc, minutes, and note shortcuts and skills (#1571)
-
-### Bug Fixes
-
-- **docs**: Hide docs `api-version` compat flag (#1580)
-
-## [v1.0.58] - 2026-06-25
-
-### Features
-
-- **sheets**: Typed table I/O and error contract, workbook import/export, and skill refresh (#1355)
-- **base**: Add Base URL and title resolve shortcuts (#1338)
-- **drive**: Add `+member-add` shortcut with wiki space member collection collaborator support (#1204)
-- **doc**: Support `create` title option (#1536)
-- **doc**: Add `im-markdown` output format for doc fetch (#1550)
-- **whiteboard**: Export whiteboard as SVG and update whiteboard via SVG (#1559)
-- **card**: Support `card.action.trigger` event with auto-fetched card content (#1528)
-- **task**: Add task event consumer (#1510)
-
-### Bug Fixes
-
-- **doc**: Prefix docs resource shortcuts (#1564)
-- **binding**: Skip unix mode audit on Windows (#1525)
-
-### Documentation
-
-- **approval**: Sync approval skill for meta API commands (#1499)
-- **doc**: Restore lark-doc style requirements (#1579)
-- **im**: Document `chat.nickname` get/update/delete (#1378)
-- **im**: Clarify audio message opus requirement (#1271)
-
-### Build
-
-- **ci**: Add public content safeguards and reduce false positives
-
-## [v1.0.57] - 2026-06-23
-
-### Features
-
-- **slides**: Add `+screenshot` to capture slide page images (or render a single `<slide>` XML snippet), returning the local file path instead of Base64 (#1358)
-- **base**: Support record comments (#1043)
-- **search**: Surface search API notices (#1413)
-
-### Bug Fixes
-
-- **mail**: Resolve folder/label filter once per `+triage list` call (#1512)
-- **meta**: Backfill enum value descriptions from options (#1541)
-- **cli**: Add missing CLI headers for git credential helper (#1539)
-
-### Documentation
-
-- **doc**: Refine rich block, path, and block ID guidance (#1508)
-- **mail**: Trim lark-mail skill context (#1527)
-- **drive**: Add permission governance workflow guidance (#1292)
-
-### Build
-
-- **ci**: Bind semantic review to workflow run head (#1551)
-
 ## [v1.0.56] - 2026-06-18
 
 ### Features
@@ -1333,12 +1212,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
-[v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61
-[v1.0.60]: https://github.com/larksuite/cli/releases/tag/v1.0.60
-[v1.0.59]: https://github.com/larksuite/cli/releases/tag/v1.0.59
-[v1.0.58]: https://github.com/larksuite/cli/releases/tag/v1.0.58
-[v1.0.57]: https://github.com/larksuite/cli/releases/tag/v1.0.57
 [v1.0.56]: https://github.com/larksuite/cli/releases/tag/v1.0.56
 [v1.0.55]: https://github.com/larksuite/cli/releases/tag/v1.0.55
 [v1.0.54]: https://github.com/larksuite/cli/releases/tag/v1.0.54

Makefile

@@ -12,7 +12,6 @@ QUALITY_GATE_DIR ?= .tmp/quality-gate
 QUALITY_GATE_MANIFEST_OUT ?= $(QUALITY_GATE_DIR)/command-manifest.json
 QUALITY_GATE_COMMAND_INDEX_OUT ?= $(QUALITY_GATE_DIR)/command-index.json
 QUALITY_GATE_FACTS_OUT ?= $(QUALITY_GATE_DIR)/facts.json
-PUBLIC_CONTENT_METADATA ?= $(QUALITY_GATE_DIR)/public-content-metadata.json
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local
 
@@ -34,7 +33,11 @@ build: fetch_meta
 	go build -trimpath -ldflags "$(LDFLAGS)" -o $(BINARY) .
 
 vet: fetch_meta
-	go vet ./...
+	# -unsafeptr=false: the macOS keychain signer dereferences dylib data-symbol
+	# addresses from purego.Dlsym (uintptr->unsafe.Pointer over stable C memory) —
+	# safe FFI, but go vet's unsafeptr can't prove it and has no inline suppress.
+	# golangci-lint still runs full govet (honoring the //nolint:govet) in CI.
+	go vet -unsafeptr=false ./...
 
 # fmt-check fails when any file would be reformatted by gofmt. Keep this
 # in sync with the fast-gate "Check formatting" step in CI.
@@ -70,8 +73,7 @@ integration-test: build
 test: vet fmt-check script-test unit-test examples-build integration-test
 
 quality-gate: build
-	mkdir -p $(QUALITY_GATE_DIR) $(dir $(QUALITY_GATE_FACTS_OUT)) $(dir $(PUBLIC_CONTENT_METADATA))
-	test -f $(PUBLIC_CONTENT_METADATA) || printf '{}\n' > $(PUBLIC_CONTENT_METADATA)
+	mkdir -p $(QUALITY_GATE_DIR) $(dir $(QUALITY_GATE_FACTS_OUT))
 	LARKSUITE_CLI_REMOTE_META=off \
 	LARKSUITE_CLI_NO_UPDATE_NOTIFIER=1 \
 	LARKSUITE_CLI_NO_SKILLS_NOTIFIER=1 \
@@ -91,7 +93,6 @@ quality-gate: build
 		--changed-from $(QUALITY_GATE_CHANGED_FROM_RESOLVED) \
 		--manifest $(QUALITY_GATE_MANIFEST_OUT) \
 		--command-index $(QUALITY_GATE_COMMAND_INDEX_OUT) \
-		--public-content-metadata $(PUBLIC_CONTENT_METADATA) \
 		--facts-out $(QUALITY_GATE_FACTS_OUT)
 
 install: build

README.md

@@ -198,7 +198,7 @@ Prefixed with `+`, designed to be friendly for both humans and AI, with smart de
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
 ```
 
 Run `lark-cli <service> --help` to see all shortcut commands.

README.zh.md

@@ -199,7 +199,7 @@ CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
 ```
 
 运行 `lark-cli <service> --help` 查看所有快捷命令。

affordance/README.md

@@ -1,49 +0,0 @@
-# Affordance
-
-Per-command usage guidance for the CLI, authored as one markdown file per domain
-(`<service>.md`). It is surfaced in `lark-cli <command> --help` and in the
-`schema` output, and read directly at runtime (lazy, cached) — there is no build
-step. Maintain these files alongside `skills/` and `shortcuts/`.
-
-## Format
-
-A small, fixed markdown subset; each file describes one domain:
-
-    # <domain>            optional `> skill: <name>` applies to every command below
-    ## <command>          the command as typed, minus `lark-cli <domain>`
-    <lead paragraph>      when to use this command
-    ### Avoid when        when not to use it / which command to use instead
-    ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
-    ### Tips              gotchas and constraints
-    ### Examples          **description** lines, each followed by a fenced command
-    ### <other heading>   a custom section; flows through verbatim
-
-Reference another command with `[[command]]` — it renders as `command` in help.
-Under `Avoid when` it means "use that one instead"; under `Prerequisites`
-("… from [[command]]") it means "get the input there first".
-
-## Example
-
-    ## messages get
-    Fetch the full content of a single message by id.
-
-    ### Avoid when
-    - Reading several at once → use [[messages batch_get]]
-
-    ### Prerequisites
-    - message_id from [[messages list]]
-
-    ### Examples
-
-    **Fetch one message**
-    ```bash
-    lark-cli mail user_mailbox.messages get --message-id "<id>"
-    ```
-
-## Notes
-
-- Write plain prose; the only convention is wrapping command references in `[[ ]]`.
-- Keep it concise and high-signal — don't restate field/flag names, id types, or
-  anything the schema and flags already show; the agent infers the rest.
-- Command-form headings resolve to method ids via the registry, so plural resource
-  names (`messages`) map to the singular method id (`message`) automatically.

affordance/contact.md

@@ -1,19 +0,0 @@
-# contact
-> skill: lark-contact
-
-## user_profiles batch_query
-Bulk-fetch personal status and signature for user ids you already have.
-
-### Avoid when
-- Need more than status/signature (name, dept, email), or don't have the open_id yet → use [[+search-user]]
-
-### Tips
-- Off by default — set include_personal_status / include_description to true under query_option
-- ids in user_ids must match --user-id-type (default open_id)
-
-### Examples
-
-**Bulk-query status and signature**
-```bash
-lark-cli contact user_profiles batch_query --data '{"user_ids":["ou_3a8b****6a7b"],"query_option":{"include_personal_status":true,"include_description":true}}'
-```

cmd/api/api.go

@@ -67,21 +67,8 @@ func NewCmdApiWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*AP
 
 	cmd := &cobra.Command{
 		Use:   "api <method> <path>",
-		Short: "Raw HTTP escape hatch — call any endpoint by path (fallback when no typed command exists)",
-		Long: `Raw HTTP escape hatch: send any Lark API request by HTTP method + path.
-
-Prefer the typed domain command when one exists — it validates parameters,
-shows the Risk level, gates destructive calls behind --yes, and carries usage
-guidance that this raw command does not. If a domain command covers your task
-(browse with ` + "`lark-cli <domain> --help`" + `), use it instead of this.
-
-Reach for ` + "`api`" + ` only for endpoints that have no typed command yet (e.g.
-newer/preview APIs), where you already have the HTTP path from the Lark docs.
-
-Examples:
-  lark-cli api GET /open-apis/calendar/v4/calendars
-  lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"open_id"}' --data @body.json`,
-		Args: cobra.ExactArgs(2),
+		Short: "Generic Lark API requests",
+		Args:  cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			opts.Method = strings.ToUpper(args[0])
 			opts.Path = args[1]

cmd/auth/auth.go

@@ -22,11 +22,6 @@ import (
 
 // NewCmdAuth creates the auth command with subcommands.
 func NewCmdAuth(f *cmdutil.Factory) *cobra.Command {
-	return NewCmdAuthWithContext(context.Background(), f)
-}
-
-// NewCmdAuthWithContext creates the auth command with subcommands.
-func NewCmdAuthWithContext(ctx context.Context, f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "auth",
 		Short: "OAuth credentials and authorization management",
@@ -43,7 +38,7 @@ func NewCmdAuthWithContext(ctx context.Context, f *cmdutil.Factory) *cobra.Comma
 	}
 	cmdutil.DisableAuthCheck(cmd)
 
-	cmd.AddCommand(NewCmdAuthLoginWithContext(ctx, f, nil))
+	cmd.AddCommand(NewCmdAuthLogin(f, nil))
 	cmd.AddCommand(NewCmdAuthLogout(f, nil))
 	cmd.AddCommand(NewCmdAuthStatus(f, nil))
 	cmd.AddCommand(NewCmdAuthScopes(f, nil))

cmd/auth/login.go

@@ -42,11 +42,6 @@ var pollDeviceToken = larkauth.PollDeviceToken
 
 // NewCmdAuthLogin creates the auth login subcommand.
 func NewCmdAuthLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Command {
-	return NewCmdAuthLoginWithContext(context.Background(), f, runF)
-}
-
-// NewCmdAuthLoginWithContext creates the auth login subcommand.
-func NewCmdAuthLoginWithContext(ctx context.Context, f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Command {
 	opts := &LoginOptions{Factory: f}
 
 	cmd := &cobra.Command{
@@ -78,7 +73,7 @@ to generate QR codes (supports ASCII and PNG formats).`,
 	cmd.Flags().StringVar(&opts.Scope, "scope", "", "scopes to request (space- or comma-separated). Combines additively with --domain/--recommend")
 	cmd.Flags().BoolVar(&opts.Recommend, "recommend", false, "request only recommended (auto-approve) scopes")
 	var helpBrand core.LarkBrand
-	if !cmdutil.IsCredentialBootstrapDisabled(ctx) && f != nil && f.Config != nil {
+	if f != nil && f.Config != nil {
 		if cfg, err := f.Config(); err == nil && cfg != nil {
 			helpBrand = cfg.Brand
 		}
@@ -270,7 +265,7 @@ func authLoginRun(opts *LoginOptions) error {
 	if err != nil {
 		return err
 	}
-	authResp, err := larkauth.RequestDeviceAuthorization(httpClient, config.AppID, config.AppSecret, config.Brand, finalScope, f.IOStreams.ErrOut)
+	authResp, err := larkauth.RequestDeviceAuthorization(opts.Ctx, httpClient, larkauth.ClientAuthFromConfig(config), config.Brand, finalScope, f.IOStreams.ErrOut)
 	if err != nil {
 		return errs.NewAuthenticationError(errs.SubtypeUnknown, "device authorization failed: %v", err).WithCause(err)
 	}
@@ -330,7 +325,7 @@ func authLoginRun(opts *LoginOptions) error {
 
 	// Step 3: Poll for token
 	log(msg.WaitingAuth)
-	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, larkauth.ClientAuthFromConfig(config), config.Brand,
 		authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 
 	if !result.OK {
@@ -420,7 +415,7 @@ func authLoginPollDeviceCode(opts *LoginOptions, config *core.CliConfig, msg *lo
 		fmt.Fprintln(f.IOStreams.ErrOut, msg.AgentTimeoutHint)
 	}
 	log(msg.WaitingAuth)
-	result := pollDeviceToken(opts.Ctx, httpClient, config.AppID, config.AppSecret, config.Brand,
+	result := pollDeviceToken(opts.Ctx, httpClient, larkauth.ClientAuthFromConfig(config), config.Brand,
 		opts.DeviceCode, 5, 600, f.IOStreams.ErrOut)
 
 	if !result.OK {

cmd/auth/login_test.go

@@ -847,7 +847,7 @@ func TestAuthLoginRun_DeviceCodeTokenNilCleansScopeCache(t *testing.T) {
 
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: true, Token: nil}
 	}
 
@@ -886,7 +886,7 @@ func TestAuthLoginRun_JSONAbort_StdoutEventOnly_StderrEmpty(t *testing.T) {
 
 	original := pollDeviceToken
 	t.Cleanup(func() { pollDeviceToken = original })
-	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
+	pollDeviceToken = func(ctx context.Context, httpClient *http.Client, ca larkauth.ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *larkauth.DeviceFlowResult {
 		return &larkauth.DeviceFlowResult{OK: false, Message: "user denied"}
 	}
 

cmd/build.go

@@ -19,7 +19,6 @@ import (
 	"github.com/larksuite/cli/cmd/service"
 	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
-	"github.com/larksuite/cli/cmd/whoami"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/apicatalog"
 	"github.com/larksuite/cli/internal/build"
@@ -90,9 +89,8 @@ func WithoutPlugins() BuildOption {
 }
 
 // WithoutStrictMode builds the complete repository-owned command tree without
-// applying user/profile strict-mode pruning or credential-backed bootstrap
-// probes. It is intended for offline inspection tools and pure local commands
-// that must not require account configuration.
+// applying user/profile strict-mode pruning. It is intended for offline
+// inspection tools, not production execution.
 func WithoutStrictMode() BuildOption {
 	return func(c *buildConfig) {
 		c.skipStrictMode = true
@@ -147,9 +145,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 			o(cfg)
 		}
 	}
-	if cfg.skipStrictMode {
-		ctx = cmdutil.ContextWithCredentialBootstrapDisabled(ctx)
-	}
 	// 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
@@ -175,10 +170,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.SetOut(cfg.streams.Out)
 	rootCmd.SetErr(cfg.streams.ErrOut)
 
-	// Root-only usage template (curated Usage synopsis + skills footer); see
-	// rootUsageTemplate.
-	rootCmd.SetUsageTemplate(rootUsageTemplate)
-
 	installTipsHelpFunc(rootCmd)
 	rootCmd.SilenceErrors = true
 	// SilenceUsage as a static field (not only in PersistentPreRun) so it also
@@ -196,10 +187,9 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	}
 
 	rootCmd.AddCommand(cmdconfig.NewCmdConfig(f))
-	rootCmd.AddCommand(auth.NewCmdAuthWithContext(ctx, f))
+	rootCmd.AddCommand(auth.NewCmdAuth(f))
 	rootCmd.AddCommand(profile.NewCmdProfile(f))
 	rootCmd.AddCommand(doctor.NewCmdDoctor(f))
-	rootCmd.AddCommand(whoami.NewCmdWhoamiWithContext(ctx, f))
 	rootCmd.AddCommand(api.NewCmdApiWithContext(ctx, f, nil))
 	rootCmd.AddCommand(schema.NewCmdSchema(f, nil))
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
@@ -215,17 +205,10 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	}
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 
-	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)
 
-	if !cfg.skipStrictMode {
-		if mode := f.ResolveStrictMode(ctx); mode.IsActive() {
-			pruneForStrictMode(rootCmd, mode)
-		}
+	if mode := f.ResolveStrictMode(ctx); mode.IsActive() && !cfg.skipStrictMode {
+		pruneForStrictMode(rootCmd, mode)
 	}
 
 	if cfg.skipPlugins {

cmd/config/config_test.go

@@ -193,7 +193,7 @@ func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
 		t.Fatalf("seed config: %v", err)
 	}
 
-	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, ""); err != nil {
+	if err := saveInitConfig("", existing, f, "cli_x", core.PlainSecret("s2"), core.BrandFeishu, "", "", nil); err != nil {
 		t.Fatalf("saveInitConfig (no --lang): %v", err)
 	}
 
@@ -206,6 +206,88 @@ func TestSaveInitConfig_OmitLangPreservesPrior(t *testing.T) {
 	}
 }
 
+func TestKeyRefFromResult_PrivateKeyJWT(t *testing.T) {
+	ref := keyRefFromResult(&configInitResult{
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel:   "lark-cli-default",
+	})
+	if ref == nil {
+		t.Fatal("keyRefFromResult returned nil")
+	}
+	if ref.Source != "tee" || ref.ID != "lark-cli-default" {
+		t.Fatalf("key ref = %#v, want tee/lark-cli-default", ref)
+	}
+
+	if ref := keyRefFromResult(&configInitResult{AuthMethod: core.AuthMethodPrivateKeyJWT}); ref != nil {
+		t.Fatalf("missing key label should not persist key ref, got %#v", ref)
+	}
+	if ref := keyRefFromResult(&configInitResult{AuthMethod: core.AuthMethodClientSecret, KeyLabel: "ignored"}); ref != nil {
+		t.Fatalf("client_secret should not persist key ref, got %#v", ref)
+	}
+	if ref := keyRefFromResult(nil); ref != nil {
+		t.Fatalf("nil result should not persist key ref, got %#v", ref)
+	}
+}
+
+func TestSaveInitConfig_PrivateKeyJWTSingleAppPersistsSecretlessAuth(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	keyRef := &core.SecretRef{Source: "tee", ID: "lark-cli-default"}
+	if err := saveInitConfig("", nil, f, "cli_pkjwt", core.SecretInput{}, core.BrandFeishu, "en_us", core.AuthMethodPrivateKeyJWT, keyRef); err != nil {
+		t.Fatalf("saveInitConfig private_key_jwt single app: %v", err)
+	}
+
+	got, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	if len(got.Apps) != 1 {
+		t.Fatalf("apps len = %d, want 1", len(got.Apps))
+	}
+	app := got.Apps[0]
+	if app.AppId != "cli_pkjwt" {
+		t.Fatalf("AppId = %q, want cli_pkjwt", app.AppId)
+	}
+	if app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Fatalf("AuthMethod = %q, want private_key_jwt", app.AuthMethod)
+	}
+	if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID != "lark-cli-default" {
+		t.Fatalf("KeyRef = %#v, want tee/lark-cli-default", app.KeyRef)
+	}
+	if app.AppSecret.Ref != nil || app.AppSecret.Plain != "" {
+		t.Fatalf("private_key_jwt config must stay secretless, AppSecret=%#v", app.AppSecret)
+	}
+}
+
+func TestSaveInitConfig_PrivateKeyJWTProfilePersistsSecretlessAuth(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+
+	keyRef := &core.SecretRef{Source: "tee", ID: "lark-cli-default"}
+	if err := saveInitConfig("prod", &core.MultiAppConfig{}, f, "cli_pkjwt", core.SecretInput{}, core.BrandLark, "en_us", core.AuthMethodPrivateKeyJWT, keyRef); err != nil {
+		t.Fatalf("saveInitConfig private_key_jwt profile: %v", err)
+	}
+
+	got, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	app := got.FindApp("prod")
+	if app == nil {
+		t.Fatalf("profile prod not saved: %#v", got.Apps)
+	}
+	if app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Fatalf("AuthMethod = %q, want private_key_jwt", app.AuthMethod)
+	}
+	if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID != "lark-cli-default" {
+		t.Fatalf("KeyRef = %#v, want tee/lark-cli-default", app.KeyRef)
+	}
+	if app.AppSecret.Ref != nil || app.AppSecret.Plain != "" {
+		t.Fatalf("private_key_jwt profile must stay secretless, AppSecret=%#v", app.AppSecret)
+	}
+}
+
 // TestConfigInitCmd_InvalidLang verifies a non-empty --lang on config init is
 // strictly validated the same way bind validates: wrong-case / typo / removed
 // codes / hyphen form all exit with ExitValidation. (Empty is a no-op.)
@@ -388,7 +470,7 @@ func TestSaveAsProfile_RejectsProfileNameCollisionWithExistingAppID(t *testing.T
 		},
 	}
 
-	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en")
+	err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "cli_prod", "app-new", core.PlainSecret("new-secret"), core.BrandLark, "en", "", nil)
 	if err == nil {
 		t.Fatal("expected conflict error")
 	}
@@ -427,6 +509,46 @@ func TestWrapSaveConfigError_PassesTypedValidationThrough(t *testing.T) {
 	}
 }
 
+func TestSaveAsProfile_UpdatePersistsPrivateKeyJWT(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	existing := &core.MultiAppConfig{
+		Apps: []core.AppConfig{{
+			Name:      "prod",
+			AppId:     "cli_prod",
+			AppSecret: core.PlainSecret("old-secret"),
+			Brand:     core.BrandFeishu,
+			Users:     []core.AppUser{{UserOpenId: "ou_1", UserName: "User"}},
+		}},
+	}
+	keyRef := &core.SecretRef{Source: "tee", ID: "lark-cli-default"}
+
+	if err := saveAsProfile(existing, keychain.KeychainAccess(&noopConfigKeychain{}), "prod", "cli_prod", core.SecretInput{}, core.BrandLark, "en_us", core.AuthMethodPrivateKeyJWT, keyRef); err != nil {
+		t.Fatalf("saveAsProfile update private_key_jwt: %v", err)
+	}
+
+	got, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatalf("LoadMultiAppConfig: %v", err)
+	}
+	app := got.FindApp("prod")
+	if app == nil {
+		t.Fatalf("profile prod not saved: %#v", got.Apps)
+	}
+	if app.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Fatalf("AuthMethod = %q, want private_key_jwt", app.AuthMethod)
+	}
+	if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID != "lark-cli-default" {
+		t.Fatalf("KeyRef = %#v, want tee/lark-cli-default", app.KeyRef)
+	}
+	if app.AppSecret.Ref != nil || app.AppSecret.Plain != "" {
+		t.Fatalf("private_key_jwt update must stay secretless, AppSecret=%#v", app.AppSecret)
+	}
+	if len(app.Users) != 1 || app.Users[0].UserOpenId != "ou_1" {
+		t.Fatalf("same-app update should preserve users, Users=%#v", app.Users)
+	}
+}
+
 func TestUpdateExistingProfileWithoutSecret_RejectsAppIDChange(t *testing.T) {
 	multi := &core.MultiAppConfig{
 		CurrentApp: "prod",

cmd/config/init.go

@@ -19,6 +19,7 @@ import (
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/i18n"
 	"github.com/larksuite/cli/internal/keychain"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 )
 
@@ -31,6 +32,7 @@ type ConfigInitOptions struct {
 	AppSecretStdin bool   // read app-secret from stdin (avoids process list exposure)
 	Brand          string
 	New            bool
+	AuthMethod     string // --auth-method for --new: "" (default client_secret) | private_key_jwt
 
 	Lang         string // raw --lang (string for cobra); normalized to canonical/"" in validateInitLang
 	langExplicit bool   // true when --lang was explicitly passed
@@ -39,6 +41,8 @@ type ConfigInitOptions struct {
 
 	ProfileName string // when set, create/update a named profile instead of replacing Apps[0]
 
+	Restore bool // Restore re-registers the app already in config to recover a lost credential
+
 	// ForceInit overrides the agent-workspace guard. Without it, running
 	// init under OPENCLAW_HOME / HERMES_HOME refuses and points the caller
 	// at config bind — which is what AI agents almost always want. Manual
@@ -81,11 +85,13 @@ if the user explicitly wants a separate app inside the Agent workspace.`,
 	}
 
 	cmd.Flags().BoolVar(&opts.New, "new", false, "create a new app directly (skip mode selection)")
+	cmd.Flags().StringVar(&opts.AuthMethod, "auth-method", "", "auth method for --new: client_secret (default) or private_key_jwt (signed by a platform key, no app secret)")
 	cmd.Flags().StringVar(&opts.AppID, "app-id", "", "App ID (non-interactive)")
 	cmd.Flags().BoolVar(&opts.AppSecretStdin, "app-secret-stdin", false, "Read App Secret from stdin to avoid process list exposure")
 	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.Restore, "restore", false, "re-register the app already in config to recover a lost credential (keychain key / app secret); reuses the stored app ID and auth method")
 	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")
 
@@ -132,7 +138,7 @@ func guardAgentWorkspace(opts *ConfigInitOptions) error {
 
 // hasAnyNonInteractiveFlag returns true if any non-interactive flag is set.
 func (o *ConfigInitOptions) hasAnyNonInteractiveFlag() bool {
-	return o.New || o.AppID != "" || o.AppSecretStdin
+	return o.New || o.Restore || o.AppID != "" || o.AppSecretStdin
 }
 
 // cleanupOldConfig clears keychain entries (AppSecret + UAT) for all apps in existing config except the app whose AppId equals skipAppID.
@@ -151,11 +157,44 @@ func cleanupOldConfig(existing *core.MultiAppConfig, f *cmdutil.Factory, skipApp
 	}
 }
 
+// removeStaleSecretForPKJWT clears a secret left in the keychain when the SAME
+// appId is migrated from client_secret to private_key_jwt. cleanupOldConfig
+// explicitly skips a matching appId, and saveAsProfile only cleans up on an
+// appId change, so a same-appId migration would orphan the old secret. This
+// fills that gap. RemoveSecretStore only deletes Source=="keychain" entries, so
+// the new pkjwt tee key handle is never touched.
+func removeStaleSecretForPKJWT(existing *core.MultiAppConfig, profileName, appID string, kc keychain.KeychainAccess) {
+	if existing == nil {
+		return
+	}
+	var prior *core.AppConfig
+	if profileName != "" {
+		if idx := findProfileIndexByName(existing, profileName); idx >= 0 {
+			prior = &existing.Apps[idx]
+		}
+	} else {
+		prior = existing.CurrentAppConfig("")
+	}
+	if prior != nil && prior.AppId == appID && !prior.AppSecret.IsZero() {
+		core.RemoveSecretStore(prior.AppSecret, kc)
+	}
+}
+
+// keyRefFromResult builds the TEE key reference to persist for a private_key_jwt
+// registration result, or nil for client_secret.
+func keyRefFromResult(r *configInitResult) *core.SecretRef {
+	if r != nil && r.AuthMethod == core.AuthMethodPrivateKeyJWT && r.KeyLabel != "" {
+		return &core.SecretRef{Source: "tee", ID: r.KeyLabel}
+	}
+	return nil
+}
+
 // saveAsOnlyApp overwrites config.json with a single-app config.
-func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	config := &core.MultiAppConfig{
 		Apps: []core.AppConfig{{
 			AppId: appId, AppSecret: secret, Brand: brand, Lang: i18n.Lang(lang), Users: []core.AppUser{},
+			AuthMethod: authMethod, KeyRef: keyRef,
 		}},
 	}
 	return core.SaveMultiAppConfig(config)
@@ -164,9 +203,11 @@ func saveAsOnlyApp(appId string, secret core.SecretInput, brand core.LarkBrand,
 // saveInitConfig saves a new/updated app config, respecting --profile mode.
 // With profileName: appends or updates the named profile (preserves other profiles).
 // Without profileName: cleans up old config and saves as the only app.
-func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmdutil.Factory, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+// authMethod/keyRef carry the credential type: ("", nil) for client_secret,
+// (private_key_jwt, &{tee,label}) for the secretless TEE flow.
+func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmdutil.Factory, appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	if profileName != "" {
-		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang)
+		return saveAsProfile(existing, f.Keychain, profileName, appId, secret, brand, lang, authMethod, keyRef)
 	}
 	cleanupOldConfig(existing, f, appId)
 	var prior i18n.Lang
@@ -175,7 +216,7 @@ func saveInitConfig(profileName string, existing *core.MultiAppConfig, f *cmduti
 			prior = app.Lang
 		}
 	}
-	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)))
+	return saveAsOnlyApp(appId, secret, brand, string(preferredLang(i18n.Lang(lang), prior)), authMethod, keyRef)
 }
 
 // wrapSaveConfigError passes an already-typed error (e.g. the --name conflict
@@ -195,7 +236,7 @@ func wrapSaveConfigError(err error) error {
 // saveAsProfile appends or updates a named profile in the config.
 // If a profile with the same name exists, it updates it; otherwise appends.
 // When updating, cleans up old keychain secrets if AppId changed.
-func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, profileName, appId string, secret core.SecretInput, brand core.LarkBrand, lang string) error {
+func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, profileName, appId string, secret core.SecretInput, brand core.LarkBrand, lang, authMethod string, keyRef *core.SecretRef) error {
 	multi := existing
 	if multi == nil {
 		multi = &core.MultiAppConfig{}
@@ -214,6 +255,8 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 		multi.Apps[idx].AppSecret = secret
 		multi.Apps[idx].Brand = brand
 		multi.Apps[idx].Lang = preferredLang(i18n.Lang(lang), multi.Apps[idx].Lang)
+		multi.Apps[idx].AuthMethod = authMethod
+		multi.Apps[idx].KeyRef = keyRef
 	} else {
 		if findAppIndexByAppID(multi, profileName) >= 0 {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument,
@@ -222,12 +265,14 @@ func saveAsProfile(existing *core.MultiAppConfig, kc keychain.KeychainAccess, pr
 		}
 		// Append new profile
 		multi.Apps = append(multi.Apps, core.AppConfig{
-			Name:      profileName,
-			AppId:     appId,
-			AppSecret: secret,
-			Brand:     brand,
-			Lang:      i18n.Lang(lang),
-			Users:     []core.AppUser{},
+			Name:       profileName,
+			AppId:      appId,
+			AppSecret:  secret,
+			Brand:      brand,
+			Lang:       i18n.Lang(lang),
+			Users:      []core.AppUser{},
+			AuthMethod: authMethod,
+			KeyRef:     keyRef,
 		})
 	}
 	return core.SaveMultiAppConfig(multi)
@@ -305,6 +350,94 @@ func updateExistingProfileWithoutSecret(existing *core.MultiAppConfig, profileNa
 	return core.SaveMultiAppConfig(existing)
 }
 
+// persistAndProbeResult saves a registration/restore result into profileName and
+// runs the post-registration probe. profileName == "" replaces the single app
+// (legacy); a named profile is updated in place. Shared by --new and --restore.
+func persistAndProbeResult(opts *ConfigInitOptions, f *cmdutil.Factory, profileName string, result *configInitResult) error {
+	existing, _ := core.LoadMultiAppConfig()
+
+	// private_key_jwt apps have no secret: persist auth method + TEE key ref.
+	// Registration success already validated the key (server bound the public
+	// key), so the app_secret probe is skipped.
+	if result.AuthMethod == core.AuthMethodPrivateKeyJWT {
+		if err := saveInitConfig(profileName, existing, f, result.AppID, core.SecretInput{}, result.Brand, opts.Lang, result.AuthMethod, keyRefFromResult(result)); err != nil {
+			return wrapSaveConfigError(err)
+		}
+		removeStaleSecretForPKJWT(existing, profileName, result.AppID, f.Keychain)
+		printLangPreferenceConfirmation(opts)
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "authMethod": result.AuthMethod, "brand": result.Brand})
+		return runProbePKJWT(opts.Ctx, f, result.Brand, result.AppID, keysigner.Active(), result.KeyLabel)
+	}
+
+	secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
+	if err != nil {
+		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
+	}
+	if err := saveInitConfig(profileName, existing, f, result.AppID, secret, result.Brand, opts.Lang, "", nil); err != nil {
+		return wrapSaveConfigError(err)
+	}
+	printLangPreferenceConfirmation(opts)
+	output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
+	return runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand)
+}
+
+// runRestoreFlow re-registers the app already in config to recover a lost
+// credential (deleted keychain key / lost app secret). It reads the existing
+// app id + auth method + brand from config (no secret needed — that's the lost
+// part) and re-runs the device-flow registration with the app id sent on begin,
+// so the server re-registers that app instead of creating a new one. The
+// re-issued credential is written back to the same profile.
+func runRestoreFlow(opts *ConfigInitOptions, existing *core.MultiAppConfig, f *cmdutil.Factory, msg *initMsg) error {
+	if existing == nil {
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "nothing to restore: no config found").
+			WithHint("run: lark-cli config init")
+	}
+	app := existing.CurrentAppConfig(opts.ProfileName)
+	if app == nil || app.AppId == "" {
+		return errs.NewConfigError(errs.SubtypeNotConfigured, "nothing to restore: no app id in config%s", profileSuffix(opts.ProfileName)).
+			WithHint("run: lark-cli config init")
+	}
+
+	restoreAppID := app.AppId
+	// Reuse the stored auth method authoritatively — never prompt. Empty on disk
+	// means client_secret (omitempty back-compat); pass it explicitly so
+	// resolveRegisterAuthMethod doesn't fall through to the interactive picker.
+	authMethod := app.AuthMethod
+	if authMethod == "" {
+		authMethod = core.AuthMethodClientSecret
+	}
+	result, err := runCreateAppFlow(opts.Ctx, f, app.Brand, authMethod, msg, restoreAppID)
+	if err != nil {
+		return err
+	}
+	if result == nil {
+		return errs.NewInternalError(errs.SubtypeSDKError, "app restore returned no result")
+	}
+
+	// Safety: if the server did not honor app_id (e.g. not yet supported), it may
+	// have created a NEW app instead of restoring. Warn so the user is not silently
+	// switched to a different app id.
+	if result.AppID != restoreAppID {
+		fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] [WARN] restore: server returned app %s, expected %s — it may have created a new app instead of restoring\n", result.AppID, restoreAppID)
+	}
+
+	// Write back to the profile we restored: an explicit --name, else the resolved
+	// app's own name. Empty name => legacy single-app replace.
+	saveProfile := opts.ProfileName
+	if saveProfile == "" {
+		saveProfile = app.Name
+	}
+	return persistAndProbeResult(opts, f, saveProfile, result)
+}
+
+// profileSuffix renders " (profile %q)" for error messages, or "" when unnamed.
+func profileSuffix(profileName string) string {
+	if profileName == "" {
+		return ""
+	}
+	return fmt.Sprintf(" (profile %q)", profileName)
+}
+
 func configInitRun(opts *ConfigInitOptions) error {
 	f := opts.Factory
 
@@ -335,6 +468,17 @@ func configInitRun(opts *ConfigInitOptions) error {
 		}
 	}
 
+	// --restore recovers an existing app; it is incompatible with creating a new
+	// app (--new) or importing one non-interactively (--app-id / stdin secret).
+	if opts.Restore {
+		if opts.New {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--restore cannot be combined with --new").WithParam("--restore")
+		}
+		if opts.AppID != "" || opts.AppSecretStdin {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--restore cannot be combined with --app-id / --app-secret-stdin").WithParam("--restore")
+		}
+	}
+
 	// Mode 1: Non-interactive
 	if opts.AppID != "" && opts.appSecret != "" {
 		brand := parseBrand(opts.Brand)
@@ -342,7 +486,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 		if err != nil {
 			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 		}
-		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang); err != nil {
+		if err := saveInitConfig(opts.ProfileName, existing, f, opts.AppID, secret, brand, opts.Lang, "", nil); err != nil {
 			return wrapSaveConfigError(err)
 		}
 		output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))
@@ -368,34 +512,26 @@ func configInitRun(opts *ConfigInitOptions) error {
 
 	msg := getInitMsg(opts.UILang)
 
+	// Mode: Restore (--restore) — re-register the app already in config.
+	if opts.Restore {
+		return runRestoreFlow(opts, existing, f, msg)
+	}
+
 	// Mode 3: Create new app directly (--new)
 	if opts.New {
-		result, err := runCreateAppFlow(opts.Ctx, f, parseBrand(opts.Brand), msg)
+		result, err := runCreateAppFlow(opts.Ctx, f, parseBrand(opts.Brand), opts.AuthMethod, msg, "")
 		if err != nil {
 			return err
 		}
 		if result == nil {
 			return errs.NewInternalError(errs.SubtypeSDKError, "app creation returned no result")
 		}
-		existing, _ := core.LoadMultiAppConfig()
-		secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
-		if err != nil {
-			return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
-		}
-		if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
-			return wrapSaveConfigError(err)
-		}
-		printLangPreferenceConfirmation(opts)
-		output.PrintJson(f.IOStreams.Out, map[string]interface{}{"appId": result.AppID, "appSecret": "****", "brand": result.Brand})
-		if err := runProbe(opts.Ctx, f, result.AppID, result.AppSecret, result.Brand); err != nil {
-			return err
-		}
-		return nil
+		return persistAndProbeResult(opts, f, opts.ProfileName, result)
 	}
 
 	// Mode 4: Interactive TUI (terminal)
 	if !opts.hasAnyNonInteractiveFlag() && f.IOStreams.IsTerminal {
-		result, err := runInteractiveConfigInit(opts.Ctx, f, msg)
+		result, err := runInteractiveConfigInit(opts.Ctx, f, opts.AuthMethod, msg)
 		if err != nil {
 			return err
 		}
@@ -406,13 +542,22 @@ func configInitRun(opts *ConfigInitOptions) error {
 
 		existing, _ := core.LoadMultiAppConfig()
 
-		if result.AppSecret != "" {
+		if result.AuthMethod == core.AuthMethodPrivateKeyJWT {
+			// Secretless create: persist auth method + TEE key ref, no secret.
+			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, core.SecretInput{}, result.Brand, opts.Lang, result.AuthMethod, keyRefFromResult(result)); err != nil {
+				return wrapSaveConfigError(err)
+			}
+			removeStaleSecretForPKJWT(existing, opts.ProfileName, result.AppID, f.Keychain)
+			if err := runProbePKJWT(opts.Ctx, f, result.Brand, result.AppID, keysigner.Active(), result.KeyLabel); err != nil {
+				return err
+			}
+		} else if result.AppSecret != "" {
 			// New secret provided (either from "create" or "existing" with input)
 			secret, err := core.ForStorage(result.AppID, core.PlainSecret(result.AppSecret), f.Keychain)
 			if err != nil {
 				return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 			}
-			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang); err != nil {
+			if err := saveInitConfig(opts.ProfileName, existing, f, result.AppID, secret, result.Brand, opts.Lang, "", nil); err != nil {
 				return wrapSaveConfigError(err)
 			}
 		} else if result.Mode == "existing" && result.AppID != "" {
@@ -517,7 +662,7 @@ func configInitRun(opts *ConfigInitOptions) error {
 	if err != nil {
 		return errs.NewInternalError(errs.SubtypeSDKError, "%v", err).WithCause(err)
 	}
-	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang); err != nil {
+	if err := saveInitConfig(opts.ProfileName, existing, f, resolvedAppId, storedSecret, parseBrand(resolvedBrand), opts.Lang, "", nil); err != nil {
 		return wrapSaveConfigError(err)
 	}
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf("Configuration saved to %s", core.GetConfigPath()))

cmd/config/init_auth_method_test.go

@@ -0,0 +1,102 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"context"
+	"crypto"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+type authMethodTestSigner struct{}
+
+func (authMethodTestSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return nil, nil
+}
+
+func (authMethodTestSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return nil, nil
+}
+
+func (authMethodTestSigner) Sign(context.Context, keysigner.KeyRef, []byte) ([]byte, string, error) {
+	return nil, "", nil
+}
+
+// TestResolveRegisterAuthMethod covers the non-interactive gating paths. The
+// darwin keychain signer is compiled into every build, so the test cannot rely
+// on the binary lacking a signer — it forces a known no-signer state for the
+// rejection cases, then registers a stub for the success case.
+func TestResolveRegisterAuthMethod(t *testing.T) {
+	f := &cmdutil.Factory{}
+
+	prevSigner := keysigner.Active()
+	t.Cleanup(func() { keysigner.Register(prevSigner) })
+	keysigner.Register(nil)
+
+	if m, err := resolveRegisterAuthMethod(f, core.AuthMethodClientSecret); err != nil || m != core.AuthMethodClientSecret {
+		t.Errorf("client_secret: got (%q, %v), want (client_secret, nil)", m, err)
+	}
+
+	if m, err := resolveRegisterAuthMethod(f, ""); err != nil || m != core.AuthMethodClientSecret {
+		t.Errorf("default: got (%q, %v), want (client_secret, nil)", m, err)
+	}
+
+	if _, err := resolveRegisterAuthMethod(f, "bogus"); err == nil {
+		t.Error("bogus auth-method: expected error")
+	}
+
+	if _, err := resolveRegisterAuthMethod(f, core.AuthMethodPrivateKeyJWT); err == nil {
+		t.Error("private_key_jwt without a signer: expected error")
+	}
+
+	keysigner.Register(authMethodTestSigner{})
+
+	if m, err := resolveRegisterAuthMethod(f, core.AuthMethodPrivateKeyJWT); err != nil || m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("private_key_jwt with signer: got (%q, %v), want (private_key_jwt, nil)", m, err)
+	}
+}
+
+// TestValidatePKJWTKeyBinding covers the guard that rejects a registration
+// resolving to private_key_jwt with no signing key bound (e.g. an existing
+// secret-based app was selected on the confirm page).
+func TestValidatePKJWTKeyBinding(t *testing.T) {
+	if err := validatePKJWTKeyBinding(core.AuthMethodPrivateKeyJWT, ""); err == nil {
+		t.Error("pkjwt with empty keyLabel: expected error")
+	}
+	if err := validatePKJWTKeyBinding(core.AuthMethodPrivateKeyJWT, "agent-key"); err != nil {
+		t.Errorf("pkjwt with keyLabel: expected nil, got %v", err)
+	}
+	if err := validatePKJWTKeyBinding(core.AuthMethodClientSecret, ""); err != nil {
+		t.Errorf("client_secret: expected nil, got %v", err)
+	}
+}
+
+// TestResolveFinalAuthMethod locks the authoritative-method logic. The 2nd case
+// is the real bug: we requested private_key_jwt but the server resolved to an
+// existing client_secret app — we must persist client_secret, not pkjwt.
+func TestResolveFinalAuthMethod(t *testing.T) {
+	if m := resolveFinalAuthMethod([]string{"client_secret", "private_key_jwt"}, core.AuthMethodClientSecret); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("prefers private_key_jwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod([]string{"client_secret"}, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodClientSecret {
+		t.Errorf("server client_secret must override requested pkjwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod(nil, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("fallback to requested when server is silent: got %q", m)
+	}
+	// Explicit empty slice (not just nil) also falls back to requested — the same
+	// len()==0 back-compat allowance the init guard relies on to let private_key_jwt
+	// proceed against an older server (see internal/auth
+	// TestRequestAppRegistrationInit_EmptySupportedAuthMethods).
+	if m := resolveFinalAuthMethod([]string{}, core.AuthMethodPrivateKeyJWT); m != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("empty []string should fall back to requested private_key_jwt: got %q", m)
+	}
+	if m := resolveFinalAuthMethod(nil, ""); m != core.AuthMethodClientSecret {
+		t.Errorf("default to client_secret: got %q", m)
+	}
+}

cmd/config/init_interactive.go

@@ -5,7 +5,11 @@ package config
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"slices"
+	"strings"
+	"time"
 
 	"github.com/charmbracelet/huh"
 	"github.com/larksuite/cli/internal/build"
@@ -13,22 +17,26 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	larkauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/auth/jwt"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/transport"
 )
 
 // configInitResult holds the result of the interactive config init flow.
 type configInitResult struct {
-	Mode      string // "create" or "existing"
-	Brand     core.LarkBrand
-	AppID     string
-	AppSecret string
+	Mode       string // "create" or "existing"
+	Brand      core.LarkBrand
+	AppID      string
+	AppSecret  string
+	AuthMethod string // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	KeyLabel   string // TEE key handle when AuthMethod == private_key_jwt
 }
 
 // runInteractiveConfigInit shows an interactive TUI for config init.
-func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, msg *initMsg) (*configInitResult, error) {
+func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, authMethodFlag string, msg *initMsg) (*configInitResult, error) {
 	// Phase 1: Choose mode
 	var mode string
 	form1 := huh.NewForm(
@@ -54,7 +62,7 @@ func runInteractiveConfigInit(ctx context.Context, f *cmdutil.Factory, msg *init
 		return runExistingAppForm(f, msg)
 	}
 
-	return runCreateAppFlow(ctx, f, "", msg)
+	return runCreateAppFlow(ctx, f, "", authMethodFlag, msg, "")
 }
 
 // runExistingAppForm shows a huh form for manually entering App ID / App Secret / Brand.
@@ -146,9 +154,59 @@ func runExistingAppForm(f *cmdutil.Factory, msg *initMsg) (*configInitResult, er
 	}, nil
 }
 
+// resolveRegisterAuthMethod decides the auth method for a new-app registration.
+// An explicit --auth-method flag wins; otherwise, on an interactive terminal with
+// a TEE signer available, the user is prompted; the default is client_secret.
+func resolveRegisterAuthMethod(f *cmdutil.Factory, flag string) (string, error) {
+	signerAvailable := keysigner.Active() != nil
+	switch flag {
+	case core.AuthMethodPrivateKeyJWT:
+		if !signerAvailable {
+			return "", errs.NewConfigError(errs.SubtypeInvalidClient,
+				"--auth-method private_key_jwt requires a platform key signer, which is unavailable on this device/build").
+				WithHint("omit --auth-method (or pass --auth-method client_secret) to register with an app secret")
+		}
+		return core.AuthMethodPrivateKeyJWT, nil
+	case core.AuthMethodClientSecret:
+		return core.AuthMethodClientSecret, nil
+	case "":
+		// fall through to interactive / default
+	default:
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"unknown --auth-method %q (use client_secret or private_key_jwt)", flag)
+	}
+
+	if signerAvailable && f.IOStreams.IsTerminal {
+		var choice string
+		form := huh.NewForm(
+			huh.NewGroup(
+				huh.NewSelect[string]().
+					Title("Authentication method").
+					Options(
+						huh.NewOption("App Secret (client_secret)", core.AuthMethodClientSecret),
+						huh.NewOption("Secure key signer, no secret (private_key_jwt)", core.AuthMethodPrivateKeyJWT),
+					).
+					Value(&choice),
+			),
+		).WithTheme(cmdutil.ThemeFeishu())
+		if err := form.Run(); err != nil {
+			if errors.Is(err, huh.ErrUserAborted) {
+				return "", output.ErrBare(1)
+			}
+			return "", err
+		}
+		return choice, nil
+	}
+	return core.AuthMethodClientSecret, nil
+}
+
 // runCreateAppFlow runs the "create new app" flow via OpenClaw device flow.
 // If brandOverride is non-empty, skip the interactive brand selection.
-func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride core.LarkBrand, msg *initMsg) (*configInitResult, error) {
+// authMethodFlag is the raw --auth-method value ("" when unset).
+// restoreAppID, when non-empty, is sent on the registration begin request so the
+// server re-registers that existing app (credential recovery) instead of creating
+// a new one. Empty preserves the normal new-app flow.
+func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride core.LarkBrand, authMethodFlag string, msg *initMsg, restoreAppID string) (*configInitResult, error) {
 	var larkBrand core.LarkBrand
 	if brandOverride != "" {
 		larkBrand = brandOverride
@@ -176,11 +234,51 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		larkBrand = parseBrand(brand)
 	}
 
-	// Step 1: Request app registration (begin)
+	authMethod, err := resolveRegisterAuthMethod(f, authMethodFlag)
+	if err != nil {
+		return nil, err
+	}
+
+	// Step 1: Request app registration (begin).
 	// Use the shared proxy-plugin-aware transport so registration traffic is not
 	// a bypass of proxy plugin mode.
 	httpClient := transport.NewHTTPClient(0)
-	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, f.IOStreams.ErrOut)
+
+	// For private_key_jwt: init to obtain a nonce, then sign a TEE attestation
+	// (carrying the public key in its jwk header) to send with begin.
+	beginOpts := larkauth.AppRegistrationBeginOptions{}
+	keyLabel := ""
+	if authMethod == core.AuthMethodPrivateKeyJWT {
+		signer := keysigner.Active() // non-nil, guaranteed by resolveRegisterAuthMethod
+		initResp, initErr := larkauth.RequestAppRegistrationInit(httpClient)
+		if initErr != nil {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration init failed: %v", initErr).WithCause(initErr)
+		}
+		// An empty SupportedAuthMethods is intentionally treated as "older server /
+		// unknown": len()==0 makes this guard false, so the requested
+		// private_key_jwt proceeds. This mirrors resolveFinalAuthMethod's
+		// back-compat fallback to the requested method. Only an explicit list that
+		// omits private_key_jwt rejects here.
+		if len(initResp.SupportedAuthMethods) > 0 && !slices.Contains(initResp.SupportedAuthMethods, core.AuthMethodPrivateKeyJWT) {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient,
+				"server does not support private_key_jwt for this app type (supported: %s)", strings.Join(initResp.SupportedAuthMethods, ", ")).
+				WithHint("register with --auth-method client_secret instead")
+		}
+		keyLabel = keysigner.DefaultKeyLabel
+		attestation, signErr := jwt.SignAttestation(ctx, signer, keysigner.KeyRef{Label: keyLabel}, initResp.Nonce, time.Now())
+		if signErr != nil {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "failed to sign registration attestation: %v", signErr).WithCause(signErr)
+		}
+		beginOpts = larkauth.AppRegistrationBeginOptions{
+			AuthMethod:      core.AuthMethodPrivateKeyJWT,
+			AuthAttestation: attestation,
+		}
+	}
+
+	// Restore flow: re-register the existing app instead of creating a new one.
+	beginOpts.RestoreAppID = restoreAppID
+
+	authResp, err := larkauth.RequestAppRegistration(httpClient, larkBrand, beginOpts, f.IOStreams.ErrOut)
 	if err != nil {
 		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration failed: %v", err).WithCause(err)
 	}
@@ -213,18 +311,28 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		return nil, errs.NewAuthenticationError(errs.SubtypeUnknown, "%v", err).WithCause(err)
 	}
 
-	// Step 4: Handle Lark brand special case
-	// If tenant_brand=lark and no client_secret, retry with lark brand endpoint
-	if result.ClientSecret == "" && result.UserInfo != nil && result.UserInfo.TenantBrand == "lark" {
-		// fmt.Fprintf(f.IOStreams.ErrOut, "%s\n", msg.DetectedLarkTenant)
+	// The final auth method is decided by the user/admin at confirmation and
+	// returned by poll — NOT necessarily what we requested. Selecting an existing
+	// client_secret app, for example, yields client_secret even though we sent
+	// private_key_jwt. Trust the result so we persist the truth.
+	finalMethod := resolveFinalAuthMethod(result.AuthMethods, authMethod)
+
+	// Lark brand special case (client_secret only): a lark-tenant app returns its
+	// secret only from the lark endpoint. private_key_jwt returns no secret, so
+	// this retry does not apply.
+	if finalMethod != core.AuthMethodPrivateKeyJWT && result.ClientSecret == "" && result.UserInfo != nil && result.UserInfo.TenantBrand == "lark" {
 		result, err = larkauth.PollAppRegistration(ctx, httpClient, core.BrandLark, authResp.DeviceCode, authResp.Interval, authResp.ExpiresIn, f.IOStreams.ErrOut)
 		if err != nil {
 			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "lark endpoint retry failed: %v", err).WithCause(err)
 		}
+		finalMethod = resolveFinalAuthMethod(result.AuthMethods, authMethod)
 	}
 
-	if result.ClientID == "" || result.ClientSecret == "" {
-		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id or client_secret")
+	if result.ClientID == "" {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_id")
+	}
+	if finalMethod != core.AuthMethodPrivateKeyJWT && result.ClientSecret == "" {
+		return nil, errs.NewConfigError(errs.SubtypeInvalidClient, "app registration succeeded but missing client_secret")
 	}
 
 	// Determine final brand from response
@@ -235,13 +343,67 @@ func runCreateAppFlow(ctx context.Context, f *cmdutil.Factory, brandOverride cor
 		finalBrand = core.BrandFeishu
 	}
 
+	// Surface a downgrade: requested private_key_jwt but the app resolved to a
+	// secret-based method (e.g. an existing app was selected). The key was NOT
+	// bound, so we must store the secret method, not private_key_jwt.
+	if authMethod == core.AuthMethodPrivateKeyJWT && finalMethod != core.AuthMethodPrivateKeyJWT {
+		fmt.Fprintf(f.IOStreams.ErrOut, "[lark-cli] note: requested private_key_jwt, but the app uses %q (e.g. an existing app was selected); storing %q.\n", finalMethod, finalMethod)
+	}
+
 	fmt.Fprintln(f.IOStreams.ErrOut)
 	output.PrintSuccess(f.IOStreams.ErrOut, fmt.Sprintf(msg.AppCreated, result.ClientID))
 
+	keyToStore := ""
+	if finalMethod == core.AuthMethodPrivateKeyJWT {
+		keyToStore = keyLabel
+	}
+	if err := validatePKJWTKeyBinding(finalMethod, keyToStore); err != nil {
+		return nil, err
+	}
 	return &configInitResult{
-		Mode:      "create",
-		Brand:     finalBrand,
-		AppID:     result.ClientID,
-		AppSecret: result.ClientSecret,
+		Mode:       "create",
+		Brand:      finalBrand,
+		AppID:      result.ClientID,
+		AppSecret:  result.ClientSecret, // empty for private_key_jwt; real secret otherwise
+		AuthMethod: finalMethod,
+		KeyLabel:   keyToStore,
 	}, nil
 }
+
+// validatePKJWTKeyBinding rejects a registration that resolved to
+// private_key_jwt without a signing key bound to it. keyLabel is non-empty only
+// when the local flow chose private_key_jwt and signed a TEE attestation; a
+// resolved method of private_key_jwt with no key handle would save an unusable
+// config (rejected later at config load, surfacing as "saved OK, fails on first
+// use"), so it is caught here at registration time instead.
+func validatePKJWTKeyBinding(finalMethod, keyLabel string) error {
+	if finalMethod == core.AuthMethodPrivateKeyJWT && keyLabel == "" {
+		return errs.NewConfigError(errs.SubtypeInvalidClient,
+			"registration resolved to private_key_jwt but no signing key was bound to this app (an existing secret-based app may have been selected)").
+			WithHint("re-register with: lark-cli config init --new --auth-method private_key_jwt")
+	}
+	return nil
+}
+
+// resolveFinalAuthMethod picks the authoritative method from the poll result,
+// preferring private_key_jwt, then client_secret. It falls back to the requested
+// method when the server returns nothing (older servers).
+func resolveFinalAuthMethod(serverMethods []string, requested string) string {
+	if len(serverMethods) == 0 {
+		if requested == "" {
+			return core.AuthMethodClientSecret
+		}
+		return requested
+	}
+	for _, m := range serverMethods {
+		if m == core.AuthMethodPrivateKeyJWT {
+			return core.AuthMethodPrivateKeyJWT
+		}
+	}
+	for _, m := range serverMethods {
+		if m == core.AuthMethodClientSecret {
+			return core.AuthMethodClientSecret
+		}
+	}
+	return serverMethods[0]
+}

cmd/config/init_probe.go

@@ -16,6 +16,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // probeTimeout is the total wall-clock budget for the credential probe step
@@ -90,3 +91,32 @@ func runProbe(parent context.Context, factory *cmdutil.Factory, appID, appSecret
 	_, _ = io.Copy(io.Discard, resp.Body)
 	return nil
 }
+
+// runProbePKJWT does a best-effort key-binding validation after a private_key_jwt
+// config is saved: it signs a client_assertion with the local platform key and
+// mints a token. A typed error (a deterministic server rejection — e.g. the key
+// is not bound to this app) is propagated so `config init` exits non-zero with
+// the canonical envelope; untyped errors (transport / HTTP / parse / timeout)
+// are swallowed (return nil). The mint itself is the probe — no second call.
+func runProbePKJWT(parent context.Context, factory *cmdutil.Factory, brand core.LarkBrand, clientID string, signer keysigner.Signer, keyLabel string) error {
+	if factory == nil || signer == nil {
+		return nil
+	}
+	httpClient, err := factory.HttpClient()
+	if err != nil {
+		return nil
+	}
+
+	ctx, cancel := context.WithTimeout(parent, probeTimeout)
+	defer cancel()
+
+	if _, err := credential.FetchTATWithAssertion(ctx, httpClient, brand, clientID, signer, keyLabel); err != nil {
+		// Typed = deterministic credential rejection → propagate. Untyped
+		// (transport / HTTP / parse / timeout) is ambiguous → stay silent.
+		if errs.IsTyped(err) {
+			return err
+		}
+		return nil
+	}
+	return nil
+}

cmd/config/init_probe_test.go

@@ -6,6 +6,11 @@ package config
 import (
 	"bytes"
 	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	crand "crypto/rand"
+	"crypto/sha256"
 	"errors"
 	"io"
 	"net/http"
@@ -17,14 +22,17 @@ import (
 	"github.com/larksuite/cli/internal/build"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // fakeRT routes requests to per-path handlers and records what it saw.
 type fakeRT struct {
 	tatHandler   func(req *http.Request) (*http.Response, error)
 	probeHandler func(req *http.Request) (*http.Response, error)
+	oauthHandler func(req *http.Request) (*http.Response, error)
 	tatCalls     int
 	probeCalls   int
+	oauthCalls   int
 	probeReq     *http.Request
 	probeBody    string
 }
@@ -48,10 +56,50 @@ func (f *fakeRT) RoundTrip(req *http.Request) (*http.Response, error) {
 			return jsonResp(200, `{"code":0,"data":{},"msg":"success"}`), nil
 		}
 		return f.probeHandler(req)
+	case strings.HasSuffix(req.URL.Path, "/authen/v2/oauth/token"):
+		f.oauthCalls++
+		if f.oauthHandler == nil {
+			return jsonResp(200, `{"access_token":"t-jwt"}`), nil
+		}
+		return f.oauthHandler(req)
 	}
 	return nil, errors.New("unexpected URL: " + req.URL.String())
 }
 
+// probeTestSigner is an in-memory real ECDSA P-256 signer used to sign the
+// client_assertion in runProbePKJWT tests (authMethodTestSigner returns a nil
+// key and cannot sign).
+type probeTestSigner struct{ key *ecdsa.PrivateKey }
+
+func newProbeTestSigner(t *testing.T) *probeTestSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), crand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &probeTestSigner{key: k}
+}
+
+func (p *probeTestSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return p.key.Public(), nil
+}
+
+func (p *probeTestSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return p.key.Public(), nil
+}
+
+func (p *probeTestSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(crand.Reader, p.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
 func jsonResp(code int, body string) *http.Response {
 	return &http.Response{
 		StatusCode: code,
@@ -285,3 +333,42 @@ func TestRunProbe_TimeoutHonored(t *testing.T) {
 	// must stay silent and not block.
 	assertSilent(t, err, errBuf)
 }
+
+// runProbePKJWT: a deterministic server rejection (invalid_client) is propagated
+// as a typed ConfigError so config init exits non-zero.
+func TestRunProbePKJWT_DeterministicReject_Propagates(t *testing.T) {
+	rt := &fakeRT{oauthHandler: func(*http.Request) (*http.Response, error) {
+		return jsonResp(401, `{"error":"invalid_client","error_description":"unknown key"}`), nil
+	}}
+	f, errBuf := fakeFactory(t, rt)
+	err := runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", newProbeTestSigner(t), "agent-key")
+	if err == nil || !errs.IsTyped(err) {
+		t.Fatalf("expected propagated typed error, got %T %v", err, err)
+	}
+	if errBuf.Len() != 0 {
+		t.Errorf("runProbePKJWT must not write stderr, got %q", errBuf.String())
+	}
+}
+
+// runProbePKJWT: ambiguous upstream noise (HTTP 503) is swallowed — silent, exit 0.
+func TestRunProbePKJWT_Ambiguous_Silent(t *testing.T) {
+	rt := &fakeRT{oauthHandler: func(*http.Request) (*http.Response, error) {
+		return jsonResp(503, `unavailable`), nil
+	}}
+	f, errBuf := fakeFactory(t, rt)
+	assertSilent(t, runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", newProbeTestSigner(t), "agent-key"), errBuf)
+}
+
+// runProbePKJWT: a successful mint returns nil.
+func TestRunProbePKJWT_Success_Silent(t *testing.T) {
+	rt := &fakeRT{} // default oauth handler returns 200 + access_token
+	f, errBuf := fakeFactory(t, rt)
+	assertSilent(t, runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", newProbeTestSigner(t), "agent-key"), errBuf)
+}
+
+// runProbePKJWT: a nil signer is a defensive no-op (should not be reached, must
+// not panic).
+func TestRunProbePKJWT_NilSigner_Silent(t *testing.T) {
+	f, errBuf := fakeFactory(t, &fakeRT{})
+	assertSilent(t, runProbePKJWT(context.Background(), f, core.BrandFeishu, "cli_x", nil, "k"), errBuf)
+}

cmd/config/init_test.go

@@ -10,9 +10,25 @@ import (
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/output"
 )
 
+// TestRunRestoreFlow_NothingToRestore covers the early guards that return before
+// any network/registration call: no config at all, and a config whose resolved
+// app has no app id (nothing to send on begin).
+func TestRunRestoreFlow_NothingToRestore(t *testing.T) {
+	// No config on disk.
+	if err := runRestoreFlow(&ConfigInitOptions{}, nil, nil, nil); err == nil {
+		t.Fatal("expected error when there is no config to restore")
+	}
+	// Config present but the resolved app has no app id.
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: ""}}}
+	if err := runRestoreFlow(&ConfigInitOptions{}, existing, nil, nil); err == nil {
+		t.Fatal("expected error when the resolved app has no app id")
+	}
+}
+
 // updateExistingProfileWithoutSecret guards four blank-input scenarios. Each
 // must surface as *ValidationError(SubtypeInvalidArgument) per RFC 6749 §5.2:
 // SubtypeInvalidClient is reserved for IAM rejection of malformed credentials,
@@ -119,3 +135,62 @@ func assertValidationParam(t *testing.T, err error, wantParam string) {
 		t.Errorf("Param = %q, want %q", valErr.Param, wantParam)
 	}
 }
+
+// countingKeychain is an in-memory KeychainAccess that records whether Remove
+// was invoked, so the stale-secret cleanup can be asserted without a real OS
+// keychain.
+type countingKeychain struct {
+	store        map[string]string
+	removeCalled bool
+}
+
+func newCountingKeychain() *countingKeychain {
+	return &countingKeychain{store: map[string]string{}}
+}
+
+func (k *countingKeychain) Get(service, account string) (string, error) {
+	v, ok := k.store[service+"/"+account]
+	if !ok {
+		return "", keychain.ErrNotFound
+	}
+	return v, nil
+}
+
+func (k *countingKeychain) Set(service, account, value string) error {
+	k.store[service+"/"+account] = value
+	return nil
+}
+
+func (k *countingKeychain) Remove(service, account string) error {
+	k.removeCalled = true
+	delete(k.store, service+"/"+account)
+	return nil
+}
+
+func TestRemoveStaleSecretForPKJWT_SameAppID(t *testing.T) {
+	kc := newCountingKeychain()
+	ref, err := core.ForStorage("cli_same", core.PlainSecret("old-secret"), kc) // → Source:"keychain"
+	if err != nil {
+		t.Fatal(err)
+	}
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: "cli_same", AppSecret: ref}}}
+	removeStaleSecretForPKJWT(existing, "", "cli_same", kc)
+	if !kc.removeCalled {
+		t.Error("same appId with keychain secret: expected kc.Remove to be invoked")
+	}
+}
+
+func TestRemoveStaleSecretForPKJWT_DifferentAppID(t *testing.T) {
+	kc := newCountingKeychain()
+	ref, _ := core.ForStorage("cli_old", core.PlainSecret("old-secret"), kc)
+	kc.removeCalled = false // ForStorage does not call Remove, but reset to be safe
+	existing := &core.MultiAppConfig{Apps: []core.AppConfig{{AppId: "cli_old", AppSecret: ref}}}
+	removeStaleSecretForPKJWT(existing, "", "cli_new", kc)
+	if kc.removeCalled {
+		t.Error("different appId: must NOT remove")
+	}
+}
+
+func TestRemoveStaleSecretForPKJWT_NilExisting(t *testing.T) {
+	removeStaleSecretForPKJWT(nil, "", "cli_x", newCountingKeychain()) // must not panic
+}

cmd/doctor/doctor.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"io"
 	"net/http"
 	"os"
 	"sync"
@@ -19,6 +20,7 @@ import (
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/identitydiag"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/update"
@@ -129,12 +131,12 @@ func doctorRun(opts *DoctorOptions) error {
 	if diagnostics.Bot.Available || diagnostics.User.Available {
 		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).
-		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", ""))
+		checks = append(checks, fail("identity_ready", "no usable bot or user identity is available", "run: lark-cli auth status --verify"))
 	}
 
+	// ── 3b. private_key_jwt / TEE signer (local; runs even with --offline) ──
+	checks = append(checks, teeSignerCheck(opts.Ctx, cfg))
+
 	// ── 4 & 5. Endpoint reachability ──
 	checks = append(checks, networkChecks(opts.Ctx, opts, ep)...)
 
@@ -148,6 +150,54 @@ func identityCheck(name string, id identitydiag.Identity) checkResult {
 	return warn(name, id.Message, id.Hint)
 }
 
+const teeUnavailableHint = "ensure the device secure hardware is accessible (Linux TPM: add your user to the 'tss' group or run with sufficient privileges)"
+
+// teeSignerCheck reports the private_key_jwt signing backend (TEE/TPM) status.
+// The probe is local hardware only (no network), so it runs even with --offline;
+// in a build without a TEE signer it short-circuits without touching any
+// hardware. It is a hard requirement for private_key_jwt apps and purely
+// informational for client_secret apps.
+func teeSignerCheck(ctx context.Context, cfg *core.CliConfig) checkResult {
+	usesPKJWT := cfg != nil && cfg.AuthMethod == core.AuthMethodPrivateKeyJWT
+	info, ok, err := keysigner.ProbeActiveHardware(ctx)
+	return teeCheckResult(info, ok, err, usesPKJWT)
+}
+
+// teeCheckResult maps a hardware probe to a doctor check. Split out from
+// teeSignerCheck so the full matrix is unit-testable without a TPM.
+func teeCheckResult(info keysigner.HardwareInfo, ok bool, probeErr error, usesPKJWT bool) checkResult {
+	const name = "tee_signer"
+
+	// No signer registered → private_key_jwt is unsupported on this build.
+	if !ok {
+		if usesPKJWT {
+			return fail(name,
+				"app uses private_key_jwt but this build has no TEE key signer",
+				"the platform key signer ships by default on macOS, Linux, and Windows/amd64; this platform (e.g. Windows/arm64) has none — use a supported platform or re-register with --auth-method client_secret")
+		}
+		return skip(name, "no TEE signer in this build (only private_key_jwt is affected; client_secret is unaffected)")
+	}
+
+	backend := info.Backend
+	if backend == "" {
+		backend = "tee"
+	}
+
+	switch {
+	case probeErr != nil:
+		return warn(name, fmt.Sprintf("%s signer present but probe errored: %s", backend, probeErr), "")
+	case info.Available:
+		if info.VendorName != "" {
+			return pass(name, fmt.Sprintf("%s TEE available (%s)", backend, info.VendorName))
+		}
+		return pass(name, fmt.Sprintf("%s TEE available", backend))
+	case usesPKJWT:
+		return fail(name, fmt.Sprintf("%s signer present but TEE unavailable: %s", backend, info.Reason), teeUnavailableHint)
+	default:
+		return warn(name, fmt.Sprintf("%s signer present but TEE unavailable: %s", backend, info.Reason), teeUnavailableHint)
+	}
+}
+
 // networkChecks probes Open API and MCP endpoints concurrently.
 func networkChecks(ctx context.Context, opts *DoctorOptions, ep core.Endpoints) []checkResult {
 	if opts.Offline {
@@ -237,14 +287,90 @@ func finishDoctor(f *cmdutil.Factory, checks []checkResult) error {
 		}
 	}
 
-	result := map[string]interface{}{
-		"ok":        allOK,
-		"workspace": core.CurrentWorkspace().Display(),
-		"checks":    checks,
+	workspace := core.CurrentWorkspace().Display()
+	// A terminal on STDOUT gets a readable report; pipes, redirects, scripts and
+	// tests keep the stable JSON contract (NO_COLOR disables ANSI styling).
+	// StdoutIsTerminal checks stdout specifically — IOStreams.IsTerminal reflects
+	// stdin, which would wrongly send the human report into `doctor | jq`.
+	if f.IOStreams.StdoutIsTerminal() {
+		renderDoctorHuman(f.IOStreams.Out, workspace, checks, allOK, os.Getenv("NO_COLOR") == "")
+	} else {
+		output.PrintJson(f.IOStreams.Out, map[string]interface{}{
+			"ok":        allOK,
+			"workspace": workspace,
+			"checks":    checks,
+		})
 	}
-	output.PrintJson(f.IOStreams.Out, result)
 	if !allOK {
 		return output.ErrBare(1)
 	}
 	return nil
 }
+
+// renderDoctorHuman writes a readable health report: one aligned line per check
+// with a colored status tag, an indented hint when present, and a summary line.
+func renderDoctorHuman(w io.Writer, workspace string, checks []checkResult, allOK, color bool) {
+	const (
+		green  = "\033[32m"
+		yellow = "\033[33m"
+		red    = "\033[31m"
+		gray   = "\033[90m"
+		bold   = "\033[1m"
+		reset  = "\033[0m"
+	)
+	colorOf := map[string]string{"pass": green, "warn": yellow, "fail": red, "skip": gray}
+	tagOf := map[string]string{"pass": "PASS", "warn": "WARN", "fail": "FAIL", "skip": "SKIP"}
+	paint := func(code, s string) string {
+		if !color || code == "" {
+			return s
+		}
+		return code + s + reset
+	}
+
+	nameW := 0
+	for _, c := range checks {
+		if len(c.Name) > nameW {
+			nameW = len(c.Name)
+		}
+	}
+
+	fmt.Fprintf(w, "\n%s  (workspace: %s)\n\n", paint(bold, "lark-cli doctor"), workspace)
+
+	var passN, warnN, failN, skipN int
+	for _, c := range checks {
+		tag := tagOf[c.Status]
+		if tag == "" {
+			tag = "????"
+		}
+		fmt.Fprintf(w, "  %s  %-*s  %s\n", paint(colorOf[c.Status], "["+tag+"]"), nameW, c.Name, c.Message)
+		if c.Hint != "" {
+			fmt.Fprintf(w, "         %-*s  %s\n", nameW, "", paint(gray, "↳ "+c.Hint))
+		}
+		switch c.Status {
+		case "pass":
+			passN++
+		case "warn":
+			warnN++
+		case "fail":
+			failN++
+		case "skip":
+			skipN++
+		}
+	}
+
+	headline := paint(green, "healthy")
+	if !allOK {
+		headline = paint(red, "problems found")
+	}
+	fmt.Fprintf(w, "\n  %s — %d passed", headline, passN)
+	if warnN > 0 {
+		fmt.Fprintf(w, ", %d warning(s)", warnN)
+	}
+	if failN > 0 {
+		fmt.Fprintf(w, ", %d failed", failN)
+	}
+	if skipN > 0 {
+		fmt.Fprintf(w, ", %d skipped", skipN)
+	}
+	fmt.Fprintln(w)
+}

cmd/doctor/doctor_test.go

@@ -7,16 +7,15 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"net/http"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
-	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/keysigner"
 )
 
 func TestNewCmdDoctor_FlagParsing(t *testing.T) {
@@ -144,85 +143,116 @@ func TestDoctorRun_SplitsBotAndMissingUserIdentity(t *testing.T) {
 	assertCheck(t, got.Checks, "identity_ready", "pass")
 }
 
-func assertCheck(t *testing.T, checks []checkResult, name, status string) {
-	t.Helper()
-	if got := findCheck(t, checks, name); got.Status != status {
-		t.Fatalf("%s status = %q, want %q", name, got.Status, status)
+func TestTeeCheckResult(t *testing.T) {
+	avail := keysigner.HardwareInfo{Backend: "tpm2", Available: true, VendorName: "ACME"}
+	unavail := keysigner.HardwareInfo{Backend: "tpm2", Reason: "open /dev/tpmrm0: permission denied"}
+
+	cases := []struct {
+		name     string
+		info     keysigner.HardwareInfo
+		ok       bool
+		probeErr error
+		pkjwt    bool
+		want     string
+	}{
+		{"no signer + private_key_jwt → fail", keysigner.HardwareInfo{}, false, nil, true, "fail"},
+		{"no signer + client_secret → skip", keysigner.HardwareInfo{}, false, nil, false, "skip"},
+		{"available + private_key_jwt → pass", avail, true, nil, true, "pass"},
+		{"available + client_secret → pass", avail, true, nil, false, "pass"},
+		{"unavailable + private_key_jwt → fail", unavail, true, nil, true, "fail"},
+		{"unavailable + client_secret → warn", unavail, true, nil, false, "warn"},
+		{"probe error → warn", keysigner.HardwareInfo{Backend: "tpm2"}, true, errors.New("boom"), true, "warn"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := teeCheckResult(tc.info, tc.ok, tc.probeErr, tc.pkjwt)
+			if got.Name != "tee_signer" {
+				t.Errorf("name = %q, want tee_signer", got.Name)
+			}
+			if got.Status != tc.want {
+				t.Errorf("status = %q, want %q (msg=%q)", got.Status, tc.want, got.Message)
+			}
+		})
 	}
 }
 
-func findCheck(t *testing.T, checks []checkResult, name string) checkResult {
-	t.Helper()
-	for _, check := range checks {
-		if check.Name == name {
-			return check
-		}
-	}
-	t.Fatalf("check %q not found in %#v", name, checks)
-	return checkResult{}
-}
-
-type fakeExtProvider struct {
-	name    string
-	account *extcred.Account
-}
-
-func (p *fakeExtProvider) Name() string { return p.name }
-func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
-	return p.account, nil
-}
-func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
-	return nil, nil
-}
-
-// 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.
-func TestDoctor_ExternalProvider_IdentityReadyHintNotBlockedCommand(t *testing.T) {
+// TestDoctorRun_TeeSignerWired proves the tee_signer check is part of doctorRun.
+// It asserts the build-independent invariant (a client_secret app must never
+// FAIL on TEE) so the test passes whether or not a signer is compiled in.
+func TestDoctorRun_TeeSignerWired(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{
 		CurrentApp: "default",
-		Apps:       []core.AppConfig{{Name: "default", AppId: "cli_x", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu}},
+		Apps: []core.AppConfig{{
+			Name: "default", AppId: "test-app",
+			AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+		}},
 	}); err != nil {
 		t.Fatalf("SaveMultiAppConfig() error = %v", err)
 	}
-
-	// Provider serves neither identity: bot unsupported, user supported but not
-	// signed in → both unavailable → identity_ready fails.
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser)}
-	cred := credential.NewCredentialProvider(
-		[]extcred.Provider{&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}},
-		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{}},
-	}
-
-	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err == nil {
-		t.Fatalf("doctorRun() = nil, want failure when no identity is available")
+	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
+		AppID: "test-app", AppSecret: "secret", Brand: core.BrandFeishu,
+	})
+	if err := doctorRun(&DoctorOptions{Factory: f, Ctx: context.Background(), Offline: true}); err != nil {
+		t.Fatalf("doctorRun() error = %v", err)
 	}
 	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())
+	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
 	}
-
-	ready := findCheck(t, got.Checks, "identity_ready")
-	if ready.Status != "fail" {
-		t.Fatalf("identity_ready status = %q, want fail", ready.Status)
+	var c *checkResult
+	for i := range got.Checks {
+		if got.Checks[i].Name == "tee_signer" {
+			c = &got.Checks[i]
+		}
 	}
-	// The summary defers to the per-identity checks; it carries no hint of its
-	// own (a command here would be wrong under an external provider).
-	if ready.Hint != "" {
-		t.Fatalf("identity_ready should carry no hint, got %q", ready.Hint)
+	if c == nil {
+		t.Fatalf("tee_signer check not present in doctor output: %#v", got.Checks)
 	}
-	user := findCheck(t, got.Checks, "user_identity")
-	if !strings.Contains(user.Hint, "external") || strings.Contains(user.Hint, "auth login") {
-		t.Fatalf("user_identity hint not external-appropriate: %q", user.Hint)
+	if c.Status == "fail" {
+		t.Errorf("tee_signer = fail for a client_secret app; want skip/warn/pass (msg=%q)", c.Message)
 	}
 }
+
+func TestRenderDoctorHuman(t *testing.T) {
+	var buf bytes.Buffer
+	checks := []checkResult{
+		pass("cli_version", "1.0.50"),
+		warn("tee_signer", "tpm2 signer present but TEE unavailable", "add your user to the 'tss' group"),
+		fail("identity_ready", "no usable identity", "run: lark-cli auth status --verify"),
+		skip("endpoint_open", "skipped (--offline)"),
+	}
+	renderDoctorHuman(&buf, "local", checks, false, false)
+	out := buf.String()
+
+	for _, want := range []string{
+		"lark-cli doctor", "workspace: local",
+		"[PASS]", "cli_version", "1.0.50",
+		"[WARN]", "tee_signer", "↳ add your user to the 'tss' group",
+		"[FAIL]", "identity_ready", "↳ run: lark-cli auth status --verify",
+		"[SKIP]", "endpoint_open",
+		"problems found", "1 passed", "1 warning(s)", "1 failed", "1 skipped",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output missing %q\n---\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "\033[") {
+		t.Errorf("color=false but ANSI escapes present:\n%s", out)
+	}
+}
+
+func assertCheck(t *testing.T, checks []checkResult, name, status string) {
+	t.Helper()
+	for _, check := range checks {
+		if check.Name == name {
+			if check.Status != status {
+				t.Fatalf("%s status = %q, want %q", name, check.Status, status)
+			}
+			return
+		}
+	}
+	t.Fatalf("check %q not found in %#v", name, checks)
+}

cmd/event/list_test.go

@@ -10,22 +10,10 @@ import (
 
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
-	eventlib "github.com/larksuite/cli/internal/event"
 
 	_ "github.com/larksuite/cli/events"
 )
 
-func TestEventLookup_VCMeetingLifecycleKeys(t *testing.T) {
-	for _, key := range []string{
-		"vc.meeting.participant_meeting_started_v1",
-		"vc.meeting.participant_meeting_joined_v1",
-	} {
-		if _, ok := eventlib.Lookup(key); !ok {
-			t.Fatalf("event.Lookup(%q) should succeed", key)
-		}
-	}
-}
-
 func TestRunList_TextOutput(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
 
@@ -38,9 +26,6 @@ func TestRunList_TextOutput(t *testing.T) {
 		"KEY", "AUTH", "PARAMS", "DESCRIPTION",
 		"im.message.receive_v1",
 		"im.message.message_read_v1",
-		"task.task.update_user_access_v2",
-		"vc.meeting.participant_meeting_started_v1",
-		"vc.meeting.participant_meeting_joined_v1",
 	} {
 		if !strings.Contains(out, want) {
 			t.Errorf("list output missing %q; full output:\n%s", want, out)
@@ -70,31 +55,4 @@ func TestRunList_JSONOutput(t *testing.T) {
 			}
 		}
 	}
-
-	gotKeys := map[string]map[string]interface{}{}
-	for _, row := range rows {
-		if key, ok := row["key"].(string); ok {
-			gotKeys[key] = row
-		}
-	}
-	var foundTask bool
-	for key, row := range gotKeys {
-		if key == "task.task.update_user_access_v2" {
-			foundTask = true
-			if row["single_consumer"] != true {
-				t.Errorf("task row single_consumer = %v, want true", row["single_consumer"])
-			}
-		}
-	}
-	if !foundTask {
-		t.Fatal("event list JSON missing task.task.update_user_access_v2")
-	}
-	for _, want := range []string{
-		"vc.meeting.participant_meeting_started_v1",
-		"vc.meeting.participant_meeting_joined_v1",
-	} {
-		if _, ok := gotKeys[want]; !ok {
-			t.Errorf("JSON list output missing %q", want)
-		}
-	}
 }

cmd/event/schema_test.go

@@ -96,73 +96,6 @@ func TestRunSchema_JSONOutput(t *testing.T) {
 	}
 }
 
-func TestRunSchema_TaskUpdateUserAccessJSON(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
-
-	if err := runSchema(f, "task.task.update_user_access_v2", true); err != nil {
-		t.Fatalf("runSchema json: %v", err)
-	}
-
-	var payload map[string]interface{}
-	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-		t.Fatalf("output is not valid JSON: %v\n%s", err, stdout.String())
-	}
-	if payload["jq_root_path"] != ".event" {
-		t.Errorf("jq_root_path = %v, want .event", payload["jq_root_path"])
-	}
-	if payload["single_consumer"] != true {
-		t.Errorf("single_consumer = %v, want true", payload["single_consumer"])
-	}
-	resolved := payload["resolved_output_schema"].(map[string]interface{})
-	props := resolved["properties"].(map[string]interface{})
-	eventProps := props["event"].(map[string]interface{})["properties"].(map[string]interface{})
-	if got := eventProps["task_guid"].(map[string]interface{})["format"]; got != "task_guid" {
-		t.Errorf("task_guid format = %v, want task_guid", got)
-	}
-	if _, ok := eventProps["event_types"].(map[string]interface{})["items"].(map[string]interface{})["enum"]; !ok {
-		t.Fatalf("event_types enum missing in schema: %#v", eventProps["event_types"])
-	}
-}
-
-func TestRunSchema_JSONOutput_VCMeetingLifecycleKeys(t *testing.T) {
-	for _, key := range []string{
-		"vc.meeting.participant_meeting_started_v1",
-		"vc.meeting.participant_meeting_joined_v1",
-	} {
-		t.Run(key, func(t *testing.T) {
-			f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "test"})
-
-			if err := runSchema(f, key, true); err != nil {
-				t.Fatalf("runSchema json: %v", err)
-			}
-
-			var payload map[string]interface{}
-			if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
-				t.Fatalf("output is not valid JSON: %v\n%s", err, stdout.String())
-			}
-			if payload["key"] != key {
-				t.Errorf("key = %v, want %s", payload["key"], key)
-			}
-			resolved, ok := payload["resolved_output_schema"].(map[string]interface{})
-			if !ok {
-				t.Fatalf("resolved_output_schema missing or wrong type: %+v", payload)
-			}
-			properties, ok := resolved["properties"].(map[string]interface{})
-			if !ok {
-				t.Fatalf("resolved_output_schema.properties missing or wrong type: %+v", resolved)
-			}
-			for _, field := range []string{"type", "event_id", "timestamp", "meeting_id", "topic", "meeting_no", "start_time", "calendar_event_id"} {
-				if _, ok := properties[field]; !ok {
-					t.Errorf("resolved output schema missing field %q: %+v", field, properties)
-				}
-			}
-			if _, ok := properties["end_time"]; ok {
-				t.Errorf("resolved output schema should not include end_time for %s: %+v", key, properties)
-			}
-		})
-	}
-}
-
 func TestSchema_RendersSubscriptionKeyMarker(t *testing.T) {
 	const syntheticKey = "test.evt_sub"
 	t.Cleanup(func() { eventlib.UnregisterKeyForTest(syntheticKey) })

cmd/root.go

@@ -11,11 +11,9 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/larksuite/cli/cmd/service"
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/platform"
 	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/deprecation"
@@ -30,60 +28,43 @@ import (
 
 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).
+USAGE:
+    lark-cli <command> [subcommand] [method] [options]
+    lark-cli api <method> <path> [--params <json>] [--data <json>]
+    lark-cli schema <service.resource.method>
 
-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`
+EXAMPLES:
+    # View upcoming events
+    lark-cli calendar +agenda
 
-// 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}}
+    # List calendar events
+    lark-cli calendar events instance_view --params '{"calendar_id":"primary","start_time":"1700000000","end_time":"1700086400"}'
 
-Aliases:
-  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+    # Search users
+    lark-cli contact +search-user --query "John"
 
-Examples:
-{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+    # Generic API call
+    lark-cli api GET /open-apis/calendar/v4/calendars
 
-Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}
+AI AGENT SKILLS:
+    lark-cli pairs with AI agent skills (Claude Code, etc.) that
+    teach the agent Lark API patterns, best practices, and workflows.
 
-{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+    Install all skills:
+        npx skills add larksuite/cli -g -y
 
-Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
-  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+    Or pick specific domains:
+        npx skills add larksuite/cli -s lark-calendar -y
+        npx skills add larksuite/cli -s lark-im -y
 
-Flags:
-{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+    Learn more: https://github.com/larksuite/cli#agent-skills
 
-Global Flags:
-{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+COMMUNITY:
+    GitHub:     https://github.com/larksuite/cli
+    Issues:     https://github.com/larksuite/cli/issues
+    Docs:       https://open.feishu.cn/document/
 
-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}}
-`
+More help: lark-cli <command> --help`
 
 // Execute runs the root command and returns the process exit code.
 // rawInvocationArgs holds os.Args[1:] captured at Execute() entry. cobra's
@@ -103,16 +84,10 @@ func Execute() int {
 	configureFlagCompletions(os.Args)
 
 	ctx := context.Background()
-	buildOpts := []BuildOption{
-		WithIO(os.Stdin, os.Stdout, os.Stderr),
-		HideProfile(isSingleAppMode()),
-	}
-	if isLocalSVGlideInvocation(rawInvocationArgs) {
-		buildOpts = append(buildOpts, WithoutStrictMode())
-	}
 	f, rootCmd, reg := buildInternal(
 		ctx, inv,
-		buildOpts...,
+		WithIO(os.Stdin, os.Stdout, os.Stderr),
+		HideProfile(isSingleAppMode()),
 	)
 
 	// --- Notices (non-blocking) ---
@@ -136,30 +111,6 @@ func Execute() int {
 	return 0
 }
 
-func isLocalSVGlideInvocation(args []string) bool {
-	positionals := make([]string, 0, 2)
-	for i := 0; i < len(args); i++ {
-		arg := args[i]
-		switch {
-		case arg == "--profile":
-			if i+1 < len(args) {
-				i++
-			}
-			continue
-		case strings.HasPrefix(arg, "--profile="):
-			continue
-		case strings.HasPrefix(arg, "-"):
-			continue
-		default:
-			positionals = append(positionals, arg)
-			if len(positionals) == 2 {
-				return positionals[0] == "slides" && positionals[1] == "+create-svglide"
-			}
-		}
-	}
-	return false
-}
-
 // 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
@@ -578,49 +529,6 @@ func availableSubcommandNames(cmd *cobra.Command) (available, deprecated []strin
 	return available, deprecated
 }
 
-// Root command help groups, so an agent sees content domains, agent tooling, and
-// CLI management as distinct blocks instead of one flat alphabetical dump.
-const (
-	groupDomains    = "lark-domains"
-	groupTooling    = "agent-tooling"
-	groupManagement = "cli-management"
-)
-
-// 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() {
-		if c.GroupID != "" {
-			continue
-		}
-		switch {
-		case tooling[c.Name()]:
-			c.GroupID = groupTooling
-		case management[c.Name()]:
-			c.GroupID = groupManagement
-		case isLarkDomain(c):
-			c.GroupID = groupDomains
-		}
-	}
-}
-
-// 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 {
-	if src, _ := cmdmeta.SourceOf(c); src == cmdmeta.SourceService {
-		return true
-	}
-	return cmdmeta.Domain(c) != ""
-}
-
 // flagDidYouMean is the root FlagErrorFunc (inherited by all subcommands). It
 // converts cobra's flag-parse errors into a typed validation envelope: an
 // unknown flag gets a focused "did you mean" hint (so agents recover even when
@@ -702,17 +610,6 @@ func installTipsHelpFunc(root *cobra.Command) {
 				defer func() { f.Hidden = true }()
 			}
 		}
-		// Domain and method commands compose their agent guidance into Long lazily
-		// here (shortcuts attach after service registration); both skip the generic
-		// bottom-of-help append below.
-		if service.PrepareDomainHelp(cmd, embeddedSkillContent) {
-			defaultHelp(cmd, args)
-			return
-		}
-		if service.PrepareMethodHelp(cmd) {
-			defaultHelp(cmd, args)
-			return
-		}
 		defaultHelp(cmd, args)
 		out := cmd.OutOrStdout()
 		if level, ok := cmdutil.GetRisk(cmd); ok {

cmd/root_test.go

@@ -5,12 +5,9 @@ package cmd
 
 import (
 	"bytes"
-	"context"
 	"encoding/json"
 	"fmt"
 	"io"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
@@ -29,27 +26,6 @@ import (
 	"github.com/larksuite/cli/internal/registry"
 )
 
-type countingKeychain struct {
-	gets    int
-	sets    int
-	removes int
-}
-
-func (k *countingKeychain) Get(service, account string) (string, error) {
-	k.gets++
-	return "", fmt.Errorf("unexpected keychain Get for %s/%s", service, account)
-}
-
-func (k *countingKeychain) Set(service, account, value string) error {
-	k.sets++
-	return fmt.Errorf("unexpected keychain Set for %s/%s", service, account)
-}
-
-func (k *countingKeychain) Remove(service, account string) error {
-	k.removes++
-	return fmt.Errorf("unexpected keychain Remove for %s/%s", service, account)
-}
-
 // TestPersistentPreRunE_AuthCheckDisabledAnnotations verifies that
 // auth, config, and schema commands have auth check disabled,
 // while api does not.
@@ -99,71 +75,12 @@ func TestPersistentPreRunE_ConfigSubcommands(t *testing.T) {
 	}
 }
 
-func TestIsLocalSVGlideInvocation(t *testing.T) {
-	tests := []struct {
-		name string
-		args []string
-		want bool
-	}{
-		{name: "local svglide", args: []string{"slides", "+create-svglide", "--action", "init"}, want: true},
-		{name: "with profile", args: []string{"--profile", "demo", "slides", "+create-svglide"}, want: true},
-		{name: "with profile equals", args: []string{"--profile=demo", "slides", "+create-svglide"}, want: true},
-		{name: "other slides shortcut", args: []string{"slides", "+create"}, want: false},
-		{name: "root help", args: []string{"--help"}, want: false},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := isLocalSVGlideInvocation(tt.args); got != tt.want {
-				t.Fatalf("isLocalSVGlideInvocation(%v) = %v, want %v", tt.args, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestLocalSVGlideRootCommandDoesNotTouchKeychain(t *testing.T) {
-	dir := t.TempDir()
-	t.Chdir(dir)
-	if err := os.WriteFile("source.md", []byte("# Demo"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	var in, out, errOut bytes.Buffer
-	kc := &countingKeychain{}
-	_, rootCmd, _ := buildInternal(
-		context.Background(),
-		cmdutil.InvocationContext{},
-		WithIO(&in, &out, &errOut),
-		WithKeychain(kc),
-		WithoutStrictMode(),
-		WithoutPlugins(),
-	)
-	rootCmd.SetArgs([]string{
-		"slides",
-		"+create-svglide",
-		"--action", "init",
-		"--title", "Demo",
-		"--input", "source.md",
-		"--out", "run-demo",
-	})
-	if err := rootCmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v\nstdout=%s\nstderr=%s", err, out.String(), errOut.String())
-	}
-	if kc.gets != 0 || kc.sets != 0 || kc.removes != 0 {
-		t.Fatalf("keychain touched: gets=%d sets=%d removes=%d", kc.gets, kc.sets, kc.removes)
-	}
-	if _, err := os.Stat(filepath.Join("run-demo", "run.json")); err != nil {
-		t.Fatalf("missing run.json: %v", err)
-	}
-}
-
 func TestRootLong_AgentSkillsLinkTargetsReadmeSection(t *testing.T) {
-	// The human skills-install guidance now lives in the root usage-template
-	// footer (below the command list), not in the agent-facing Long.
-	if !strings.Contains(rootUsageTemplate, "https://github.com/larksuite/cli#agent-skills") {
-		t.Fatalf("root help footer should link to the README Agent Skills section, got:\n%s", rootUsageTemplate)
+	if !strings.Contains(rootLong, "https://github.com/larksuite/cli#agent-skills") {
+		t.Fatalf("root help should link to the README Agent Skills section, got:\n%s", rootLong)
 	}
-	if strings.Contains(rootUsageTemplate, "https://github.com/larksuite/cli#install-ai-agent-skills") {
-		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootUsageTemplate)
+	if strings.Contains(rootLong, "https://github.com/larksuite/cli#install-ai-agent-skills") {
+		t.Fatalf("root help should not reference the removed install-ai-agent-skills anchor, got:\n%s", rootLong)
 	}
 }
 

cmd/root_upgrade.go

@@ -1,90 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"bufio"
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/update"
-	"github.com/spf13/cobra"
-)
-
-// runRootUpgrade locates the registered `update` subcommand and runs it, so the
-// interactive root-command upgrade reuses exactly `lark-cli update` behavior
-// (install-method detection, output, error handling). Package-level var so
-// tests can stub it and avoid real network / self-update.
-var runRootUpgrade = func(cmd *cobra.Command) {
-	for _, c := range cmd.Root().Commands() {
-		if c.Name() == "update" && c.RunE != nil {
-			_ = c.RunE(c, nil) // update prints its own output/errors; swallow here
-			return
-		}
-	}
-}
-
-// 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
-// AND no flag tokens in the raw invocation.
-func isBareRootInvocation(args []string) bool {
-	return len(args) == 0 && len(flagTokensInArgs(rawInvocationArgs)) == 0
-}
-
-// readYes reads one line and reports whether it is an affirmative y/yes.
-// EOF / empty / anything else → false (default No, matching the [y/N] prompt).
-func readYes(r io.Reader) bool {
-	line, _ := bufio.NewReader(r).ReadString('\n')
-	switch strings.ToLower(strings.TrimSpace(line)) {
-	case "y", "yes":
-		return true
-	default:
-		return false
-	}
-}
-
-// 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) {
-	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 := update.CheckCached(build.Version)
-	if info == nil {
-		return
-	}
-	fmt.Fprintf(ios.ErrOut, "lark-cli %s available (current %s). Upgrade now? [y/N]: ", info.Latest, info.Current)
-	if !readYes(ios.In) {
-		return
-	}
-	runRootUpgrade(cmd)
-}
-
-// installRootUpgradePrompt wraps the root command's RunE (set to
-// 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) {
-	inner := root.RunE
-	if inner == nil {
-		return
-	}
-	root.RunE = func(cmd *cobra.Command, args []string) error {
-		if isBareRootInvocation(args) {
-			offerRootUpgrade(f, cmd)
-		}
-		return inner(cmd, args)
-	}
-}

cmd/root_upgrade_test.go

@@ -1,191 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"bytes"
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/internal/build"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/spf13/cobra"
-)
-
-func writeUpdateState(t *testing.T, dir, 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 {
-		t.Fatal(err)
-	}
-}
-
-func TestReadYes(t *testing.T) {
-	cases := map[string]bool{
-		"y\n": true, "Y\n": true, "yes\n": true, "YES\n": true, " y \n": true,
-		"n\n": false, "\n": false, "": false, "nope\n": false, "yeah\n": false,
-	}
-	for in, want := range cases {
-		if got := readYes(strings.NewReader(in)); got != want {
-			t.Errorf("readYes(%q) = %v, want %v", in, got, want)
-		}
-	}
-}
-
-func TestIsBareRootInvocation(t *testing.T) {
-	orig := rawInvocationArgs
-	t.Cleanup(func() { rawInvocationArgs = orig })
-
-	rawInvocationArgs = nil
-	if !isBareRootInvocation([]string{}) {
-		t.Error("empty args + no raw flag tokens should be bare")
-	}
-	rawInvocationArgs = []string{"--profile", "x"}
-	if isBareRootInvocation([]string{}) {
-		t.Error("flag token present → not bare")
-	}
-	rawInvocationArgs = nil
-	if isBareRootInvocation([]string{"im"}) {
-		t.Error("positional arg → not bare")
-	}
-}
-
-func TestOfferRootUpgrade(t *testing.T) {
-	origV := build.Version
-	build.Version = "1.0.0" // release version so shouldSkip()==false
-	t.Cleanup(func() { build.Version = origV })
-
-	origRun := runRootUpgrade
-	t.Cleanup(func() { runRootUpgrade = origRun })
-
-	// This test builds a Factory literal (no NewDefault), so it never runs
-	// workspace detection; pin the process-global workspace to Local so
-	// statePath() resolves under LARKSUITE_CLI_CONFIG_DIR rather than a stale
-	// subdir inherited from a prior test in the package.
-	origWS := core.CurrentWorkspace()
-	t.Cleanup(func() { core.SetCurrentWorkspace(origWS) })
-	core.SetCurrentWorkspace(core.WorkspaceLocal)
-
-	cases := []struct {
-		name                string
-		in, out, err        bool
-		input               string
-		latest              string // "" → no state file (CheckCached nil)
-		optOut              bool
-		wantPrompt, wantRun bool
-	}{
-		{"all-tty+y", true, true, true, "y\n", "2.0.0", false, true, true},
-		{"all-tty+yes", true, true, true, "yes\n", "2.0.0", false, true, true},
-		{"all-tty+n", true, true, true, "n\n", "2.0.0", false, true, false},
-		{"all-tty+empty", true, true, true, "\n", "2.0.0", false, true, false},
-		{"all-tty+eof", true, true, true, "", "2.0.0", false, true, false},
-		{"stdin-not-tty", false, true, true, "y\n", "2.0.0", false, false, false},
-		{"stdout-not-tty", true, false, true, "y\n", "2.0.0", false, false, false},
-		{"stderr-not-tty", true, true, false, "y\n", "2.0.0", false, false, false},
-		{"no-newer-version", true, true, true, "y\n", "", false, false, false},
-		{"already-latest", true, true, true, "y\n", "1.0.0", false, false, false}, // post-upgrade: current == cached latest → no prompt
-		{"cache-older-than-current", true, true, true, "y\n", "0.9.0", false, false, false},
-		{"opt-out", true, true, true, "y\n", "2.0.0", true, false, false},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			dir := t.TempDir()
-			t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-			// Clear env that update.shouldSkip treats as "suppress" so the
-			// test is deterministic regardless of host (GitHub Actions sets
-			// CI=true, which would otherwise suppress the prompt).
-			t.Setenv("CI", "")
-			t.Setenv("BUILD_NUMBER", "")
-			t.Setenv("RUN_ID", "")
-			t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "")
-			if tc.latest != "" {
-				writeUpdateState(t, dir, tc.latest)
-			}
-			if tc.optOut {
-				t.Setenv("LARKSUITE_CLI_NO_UPDATE_NOTIFIER", "1")
-			}
-			called := false
-			runRootUpgrade = func(*cobra.Command) { called = true }
-
-			var errBuf bytes.Buffer
-			f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
-				In:               strings.NewReader(tc.input),
-				Out:              &bytes.Buffer{},
-				ErrOut:           &errBuf,
-				IsTerminal:       tc.in,
-				OutIsTerminal:    tc.out,
-				StderrIsTerminal: tc.err,
-			}}
-			offerRootUpgrade(f, &cobra.Command{})
-
-			gotPrompt := strings.Contains(errBuf.String(), "available")
-			if gotPrompt != tc.wantPrompt {
-				t.Errorf("prompt: got %v want %v (stderr=%q)", gotPrompt, tc.wantPrompt, errBuf.String())
-			}
-			if called != tc.wantRun {
-				t.Errorf("runRootUpgrade called: got %v want %v", called, tc.wantRun)
-			}
-		})
-	}
-}
-
-func TestInstallRootUpgradePromptPreservesInner(t *testing.T) {
-	orig := rawInvocationArgs
-	t.Cleanup(func() { rawInvocationArgs = orig })
-	rawInvocationArgs = nil
-
-	innerCalls := 0
-	root := &cobra.Command{Use: "lark-cli"}
-	root.RunE = func(cmd *cobra.Command, args []string) error { innerCalls++; return nil }
-
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
-		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
-	}}
-	installRootUpgradePrompt(f, root)
-
-	if err := root.RunE(root, []string{}); err != nil {
-		t.Fatalf("bare RunE err = %v", err)
-	}
-	if err := root.RunE(root, []string{"im"}); err != nil {
-		t.Fatalf("non-bare RunE err = %v", err)
-	}
-	if innerCalls != 2 {
-		t.Errorf("inner RunE should run for both bare and non-bare, got %d", innerCalls)
-	}
-}
-
-// TestRunRootUpgradeDispatchesToUpdate covers the real runRootUpgrade dispatch
-// path (not the stub used elsewhere): from any command it must locate the
-// registered "update" subcommand via cmd.Root() and invoke its RunE.
-func TestRunRootUpgradeDispatchesToUpdate(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"}
-	ran := 0
-	root.AddCommand(&cobra.Command{Use: "update", RunE: func(*cobra.Command, []string) error { ran++; return nil }})
-	child := &cobra.Command{Use: "im"}
-	root.AddCommand(child)
-
-	runRootUpgrade(child) // child.Root() resolves to root, which has "update"
-
-	if ran != 1 {
-		t.Errorf("runRootUpgrade should locate and run update's RunE once, got %d", ran)
-	}
-}
-
-// TestInstallRootUpgradePromptNilInnerNoop covers the inner == nil guard:
-// when root has no RunE, installRootUpgradePrompt must not wrap it.
-func TestInstallRootUpgradePromptNilInnerNoop(t *testing.T) {
-	root := &cobra.Command{Use: "lark-cli"} // RunE is nil
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{
-		In: strings.NewReader(""), Out: &bytes.Buffer{}, ErrOut: &bytes.Buffer{},
-	}}
-	installRootUpgradePrompt(f, root)
-	if root.RunE != nil {
-		t.Error("installRootUpgradePrompt must not wrap a nil RunE (inner==nil guard)")
-	}
-}

cmd/service/affordance.go

@@ -4,211 +4,41 @@
 package service
 
 import (
-	"encoding/json"
 	"fmt"
-	"io/fs"
 	"strings"
 
-	"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/spf13/cobra"
 )
 
-// PrepareDomainHelp appends navigational guidance (routing line, risk legend,
-// skill pointer) to a top-level Lark domain's description, returning false for
-// anything that is not such a domain. Built lazily at help time because
-// shortcuts attach after service registration. skillFS (nil-safe) gates the
-// skill pointer.
-//
-// A hand-authored Long is preserved as the base (e.g. event's "Use 'event
-// consume <EventKey>'…"); service domains carry only a Short at this point, so
-// 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 {
-	if cmd.Annotations[schemaPathAnnotation] != "" {
-		return false // a method command
-	}
-	// Direct child of root only — so Domain() reads this command's own tag, and
-	// nested resource groups are excluded.
-	if cmd.Parent() == nil || cmd.Parent().Parent() != nil {
-		return false
-	}
-	// A domain is service-sourced or shortcut-tagged; CLI tooling has neither.
-	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceService && cmdmeta.Domain(cmd) == "" {
-		return false
-	}
-	if !cmd.HasAvailableSubCommands() {
-		return false
-	}
-
-	hasShortcuts, hasResources := false, false
-	for _, c := range cmd.Commands() {
-		if c.Hidden || c.Name() == "help" || c.Name() == "completion" {
-			continue
-		}
-		if strings.HasPrefix(c.Name(), "+") {
-			hasShortcuts = true
-		} else {
-			hasResources = true
-		}
-	}
-
-	var b strings.Builder
-	b.WriteString(domainHelpBase(cmd))
-	if hasShortcuts && hasResources { // routing only matters when both styles exist
-		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.")
-	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
-}
-
-// domainHelpBase returns the description to seed domain help with — the
-// hand-authored Long when present, else the Short — captured once into an
-// annotation so re-rendering reuses the pristine text instead of the
-// already-augmented Long.
-func domainHelpBase(cmd *cobra.Command) string {
-	if base, ok := cmd.Annotations[domainBaseAnnotation]; ok {
-		return base
-	}
-	base := cmd.Long
-	if base == "" {
-		base = cmd.Short
-	}
-	if cmd.Annotations == nil {
-		cmd.Annotations = map[string]string{}
-	}
-	cmd.Annotations[domainBaseAnnotation] = base
-	return base
-}
-
-// methodLong is the build-time Long (description + schema pointer +
-// params-only addendum). Agent guidance is added lazily by PrepareMethodHelp,
-// so command construction never parses the overlay.
-func methodLong(description, schemaPath, paramsOnly string) string {
+// methodLong composes a method command's long help in one place: the
+// description, the affordance guidance block (when the method has one), the
+// pointer to the full schema, and the params-only addendum (params whose flag
+// name is taken — paramFlagBinder.paramsOnlyHelp, "" when none). Affordance
+// sits near the top so an agent sees when-to-use and few-shot examples before
+// the flag list.
+func methodLong(description, affordance, schemaPath, paramsOnly string) string {
 	var b strings.Builder
 	b.WriteString(description)
-	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
+	if affordance != "" {
+		b.WriteString("\n\n")
+		b.WriteString(affordance)
+	}
+	fmt.Fprintf(&b, "\n\nView parameter definitions before calling:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(paramsOnly)
 	return b.String()
 }
 
-// Annotation keys PrepareMethodHelp reads to rebuild a method command's Long.
-const (
-	affordanceServiceAnnotation = "affordance-service"
-	affordanceMethodAnnotation  = "affordance-method"
-	schemaPathAnnotation        = "method-schema-path"
-	paramsOnlyAnnotation        = "method-params-only"
-	domainBaseAnnotation        = "affordance-domain-base"
-)
-
-// setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
-// few strings is the only build-time cost; the overlay stays untouched).
-func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, paramsOnly string) {
-	if cmd.Annotations == nil {
-		cmd.Annotations = map[string]string{}
-	}
-	if service != "" && methodID != "" {
-		cmd.Annotations[affordanceServiceAnnotation] = service
-		cmd.Annotations[affordanceMethodAnnotation] = methodID
-	}
-	cmd.Annotations[schemaPathAnnotation] = schemaPath
-	if paramsOnly != "" {
-		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
-	}
-}
-
-// PrepareMethodHelp rebuilds a generated method command's Long with the agent
-// guidance at the TOP (Risk, then the affordance block, then the schema
-// pointer), returning false for non-method commands. The overlay is parsed
-// here — only when help is rendered.
-func PrepareMethodHelp(cmd *cobra.Command) bool {
-	ann := cmd.Annotations
-	if ann == nil {
-		return false
-	}
-	schemaPath, ok := ann[schemaPathAnnotation]
-	if !ok {
-		return false
-	}
-
-	var b strings.Builder
-	b.WriteString(cmd.Short)
-	if level, ok := cmdutil.GetRisk(cmd); ok {
-		// --yes asserts the USER confirmed; the agent must not self-approve.
-		if level == cmdutil.RiskHighRiskWrite {
-			fmt.Fprintf(&b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
-		} else {
-			fmt.Fprintf(&b, "\n\nRisk: %s", level)
-		}
-	}
-
-	var skills []string
-	if raw, ok := affordanceRaw(cmd); ok {
-		if block := renderAffordance(meta.Method{Affordance: raw}); block != "" {
-			b.WriteString("\n\n")
-			b.WriteString(block)
-		}
-		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
-			skills = a.Skills
-		}
-	}
-
-	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
-	b.WriteString(ann[paramsOnlyAnnotation])
-
-	if len(skills) > 0 {
-		b.WriteString("\n\nWorkflow skill (end-to-end usage):")
-		for _, s := range skills {
-			fmt.Fprintf(&b, "\n  lark-cli skills read %s", s)
-		}
-	}
-
-	cmd.Long = b.String()
-	return true
-}
-
-// affordanceLookup is the overlay source; a package var so tests can inject.
-var affordanceLookup = affordance.For
-
-// RenderAffordanceForCmd renders a method command's affordance block, or "" when
-// it carries none.
-func RenderAffordanceForCmd(cmd *cobra.Command) string {
-	raw, ok := affordanceRaw(cmd)
-	if !ok {
-		return ""
-	}
-	return renderAffordance(meta.Method{Affordance: raw})
-}
-
-func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
-	if cmd.Annotations == nil {
-		return nil, false
-	}
-	service := cmd.Annotations[affordanceServiceAnnotation]
-	methodID := cmd.Annotations[affordanceMethodAnnotation]
-	if service == "" || methodID == "" {
-		return nil, false
-	}
-	return affordanceLookup(service, methodID)
-}
-
-// renderAffordance renders a method's affordance as a help block, or "" when it
-// has none. Sections are joined with blank lines so they scan as distinct groups.
+// renderAffordance renders a method's affordance as a help block — when to use,
+// prerequisites, and (most importantly for agents) few-shot Examples — or "" when
+// the method carries no affordance. It reads the single typed model
+// (meta.Method.ParsedAffordance) so the help and the envelope agree on shape.
 func renderAffordance(m meta.Method) string {
 	a, ok := m.ParsedAffordance()
 	if !ok {
 		return ""
 	}
 
-	var sections []string
+	var b strings.Builder
 	bullets := func(title string, items []string) {
 		var nonEmpty []string
 		for _, it := range items {
@@ -219,18 +49,15 @@ func renderAffordance(m meta.Method) string {
 		if len(nonEmpty) == 0 {
 			return
 		}
-		var s strings.Builder
-		fmt.Fprintf(&s, "%s:\n", title)
+		fmt.Fprintf(&b, "%s:\n", title)
 		for _, it := range nonEmpty {
-			fmt.Fprintf(&s, "  • %s\n", it)
+			fmt.Fprintf(&b, "  • %s\n", it)
 		}
-		sections = append(sections, strings.TrimRight(s.String(), "\n"))
 	}
 
 	bullets("When to use", a.UseWhen)
-	bullets("Avoid when", a.AvoidWhen)
+	bullets("Avoid when", a.DoNotUseWhen)
 	bullets("Prerequisites", a.Prerequisites)
-	bullets("Tips", a.Tips)
 	if len(a.Examples) > 0 {
 		var lines []string
 		for _, ex := range a.Examples {
@@ -244,13 +71,10 @@ func renderAffordance(m meta.Method) string {
 			}
 		}
 		if len(lines) > 0 {
-			sections = append(sections, "Examples:\n"+strings.Join(lines, "\n"))
+			fmt.Fprintf(&b, "Examples:\n%s\n", strings.Join(lines, "\n"))
 		}
 	}
-	for _, ext := range a.Extensions {
-		bullets(ext.Label, ext.Items)
-	}
 	bullets("Related", a.Related)
 
-	return strings.Join(sections, "\n\n")
+	return strings.TrimRight(b.String(), "\n")
 }

cmd/service/affordance_test.go

@@ -8,18 +8,15 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/meta"
-	"github.com/spf13/cobra"
 )
 
 func TestRenderAffordance(t *testing.T) {
 	raw := json.RawMessage(`{
 		"use_when": ["发送文本消息"],
-		"avoid_when": ["群已解散"],
+		"do_not_use_when": ["群已解散"],
 		"prerequisites": ["已获取 chat_id"],
-		"tips": ["富文本用 msg_type=post"],
 		"examples": [
 			{"description":"发一条文本","command":"lark-cli im messages create --params '{...}'"},
 			{"command":"lark-cli im messages list"},
@@ -32,7 +29,6 @@ func TestRenderAffordance(t *testing.T) {
 		"When to use:", "发送文本消息",
 		"Avoid when:", "群已解散",
 		"Prerequisites:", "已获取 chat_id",
-		"Tips:", "富文本用 msg_type=post",
 		"Examples:", "发一条文本", "lark-cli im messages create --params '{...}'",
 		"lark-cli im messages list", // example with no description -> bare command line
 		"Related:", "im.messages.list",
@@ -52,12 +48,9 @@ func TestRenderAffordance(t *testing.T) {
 	}
 }
 
-// Affordance is rendered lazily (at --help time) rather than baked into the
-// command's Long, so building a command never carries the affordance block —
-// even for a method whose metadata happens to declare one.
-func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
+func TestServiceMethod_AffordanceInLong(t *testing.T) {
 	withAff := map[string]interface{}{
-		"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息",
+		"path": "messages", "httpMethod": "POST", "description": "发送消息",
 		"affordance": map[string]interface{}{
 			"examples": []interface{}{
 				map[string]interface{}{"description": "发文本", "command": "lark-cli im messages create ..."},
@@ -66,120 +59,14 @@ func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
 	}
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withAff), "create", "messages", nil)
-	if strings.Contains(cmd.Long, "Examples:") {
-		t.Errorf("affordance must not be baked into Long (lazy):\n%s", cmd.Long)
+	if !strings.Contains(cmd.Long, "Examples:") || !strings.Contains(cmd.Long, "lark-cli im messages create ...") {
+		t.Errorf("affordance examples not in command Long:\n%s", cmd.Long)
 	}
-	// The lookup ref is recorded so the help path can resolve it later.
-	if cmd.Annotations[affordanceServiceAnnotation] != "im" || cmd.Annotations[affordanceMethodAnnotation] != "messages.create" {
-		t.Errorf("affordance ref annotations = %v, want im/messages.create", cmd.Annotations)
-	}
-}
-
-// RenderAffordanceForCmd resolves a command's overlay through the (injectable)
-// lookup and renders it; commands without a ref render nothing.
-func TestRenderAffordanceForCmd(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
-		if service != "im" || methodID != "messages.create" {
-			return nil, false
-		}
-		return json.RawMessage(`{"use_when":["发文本消息"],"tips":["富文本用 msg_type=post"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), true
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
-	withRef := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
-	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withRef), "create", "messages", nil)
-	block := RenderAffordanceForCmd(cmd)
-	for _, want := range []string{"When to use:", "发文本消息", "Tips:", "富文本用 msg_type=post", "Examples:", "lark-cli im messages create ..."} {
-		if !strings.Contains(block, want) {
-			t.Errorf("RenderAffordanceForCmd missing %q in:\n%s", want, block)
-		}
-	}
-
-	// No overlay for this method id -> empty block.
-	noRef := map[string]interface{}{"id": "x.list", "path": "x", "httpMethod": "GET", "description": "d"}
-	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(noRef), "list", "x", nil)
-	if got := RenderAffordanceForCmd(cmd2); got != "" {
-		t.Errorf("method with no overlay should render nothing, got:\n%s", got)
-	}
-}
-
-// PrepareMethodHelp composes the guidance into Long at the top: description,
-// then the affordance block, then the full-schema pointer — so an agent reads
-// when-to-use/examples before the flag list.
-func TestPrepareMethodHelp(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
-		return json.RawMessage(`{"use_when":["发文本消息"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), 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)
-
-	if !PrepareMethodHelp(cmd) {
-		t.Fatal("PrepareMethodHelp returned false for a service-method command")
-	}
-	long := cmd.Long
-	// Description leads; affordance block sits above the schema pointer.
-	descAt := strings.Index(long, "发送消息")
-	useAt := strings.Index(long, "When to use:")
-	exAt := strings.Index(long, "Examples:")
-	schemaAt := strings.Index(long, "Full parameter schema:")
-	if descAt != 0 {
-		t.Errorf("description should lead Long, got:\n%s", long)
-	}
-	if !(descAt < useAt && useAt < exAt && exAt < schemaAt) {
-		t.Errorf("order should be description < affordance < schema pointer; got desc=%d use=%d ex=%d schema=%d\n%s", descAt, useAt, exAt, schemaAt, long)
-	}
-
-	// A non-service command (no schema-path annotation) is left untouched.
-	if PrepareMethodHelp(&cobra.Command{Use: "plain"}) {
-		t.Error("PrepareMethodHelp should return false for a non-service command")
-	}
-}
-
-// domainCmd wires a domain-tagged command with a subcommand under a root, the
-// shape PrepareDomainHelp expects.
-func domainCmd(short, long string) *cobra.Command {
-	root := &cobra.Command{Use: "root"}
-	dom := &cobra.Command{Use: "event", Short: short, Long: long}
-	cmdmeta.SetDomain(dom, "event")
-	dom.AddCommand(&cobra.Command{Use: "consume", Run: func(*cobra.Command, []string) {}})
-	root.AddCommand(dom)
-	return dom
-}
-
-func TestPrepareDomainHelp_PreservesHandAuthoredLong(t *testing.T) {
-	const long = "Unified event consumption system. Use 'event consume <EventKey>'."
-	dom := domainCmd("Consume and manage real-time events", long)
-
-	if !PrepareDomainHelp(dom, nil) {
-		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
-	}
-	if !strings.HasPrefix(dom.Long, long) {
-		t.Errorf("hand-authored Long must lead; got:\n%s", dom.Long)
-	}
-	if !strings.Contains(dom.Long, "Risk levels") {
-		t.Errorf("domain guidance should be appended; got:\n%s", dom.Long)
-	}
-
-	// Re-rendering must not append the guidance a second time.
-	PrepareDomainHelp(dom, nil)
-	if n := strings.Count(dom.Long, "Risk levels"); n != 1 {
-		t.Errorf("guidance appended %d times across re-renders, want 1:\n%s", n, dom.Long)
-	}
-}
-
-// A service domain carries only a Short at help time; it seeds the base.
-func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
-	dom := domainCmd("Message and group chat management", "")
-	if !PrepareDomainHelp(dom, nil) {
-		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
-	}
-	if !strings.HasPrefix(dom.Long, "Message and group chat management") {
-		t.Errorf("Short should seed Long when no hand-authored Long exists; got:\n%s", dom.Long)
+
+	// A method with no affordance adds no guidance block.
+	plain := map[string]interface{}{"path": "x", "httpMethod": "GET", "description": "d"}
+	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(plain), "list", "x", nil)
+	if strings.Contains(cmd2.Long, "Examples:") {
+		t.Errorf("no-affordance method should have no Examples in Long:\n%s", cmd2.Long)
 	}
 }

cmd/service/flaggroups_test.go

@@ -60,11 +60,8 @@ func TestServiceFlagGroups_AgentContract(t *testing.T) {
 	if i := idx("--chat-id"); i < iParams || i > iBody {
 		t.Errorf("--chat-id not under API Parameters:\n%s", out)
 	}
-	// The redundant "<name>, required|optional." prefix is gone: required-ness is
-	// carried by the Required:/Optional: subheadings, and the snake-case --params
-	// key by the schema envelope — so it isn't echoed on every flag line.
-	if strings.Contains(out, "chat_id, required") || strings.Contains(out, "member_id_type, optional") {
-		t.Errorf("redundant <name>, required/optional prefix should not appear:\n%s", out)
+	if !strings.Contains(out, "chat_id, required") {
+		t.Errorf("typed flag help format wrong:\n%s", out)
 	}
 	if !strings.Contains(out, "enum: open_id=以 open_id 标识用户|user_id=以 user_id 标识用户") {
 		t.Errorf("expected compact enum value=meaning inline:\n%s", out)

cmd/service/paramhelp.go

@@ -30,11 +30,6 @@ func fieldFacts(f meta.Field) []string {
 	if d := sanitizeFieldDesc(f.Description); d != "" {
 		facts = append(facts, d)
 	}
-	if f.CanonicalType() == "boolean" {
-		// cobra shows no type word for bools and swallows a separate value as a
-		// positional, so spell out the presence-only contract.
-		facts = append(facts, "bool flag (presence = true; omit for false; takes no value)")
-	}
 	if opts := f.EnumOptions(); len(opts) > 0 {
 		facts = append(facts, "enum: "+formatEnumInline(opts))
 	}
@@ -47,15 +42,20 @@ func fieldFacts(f meta.Field) []string {
 	return facts
 }
 
-// paramFlagUsage renders the typed param flag's help line: the field's facts
-// joined inline. Required/optional is not repeated here — the grouped help's
-// Required:/Optional: subheadings already partition the flags — and the
-// snake-case --params key is carried by the schema envelope (each param's
-// property + "flag") and the params-only addendum, so it isn't echoed on every
-// line either. Returns "" when the field has no facts (cobra then shows the bare
-// flag with its type).
+// paramFlagUsage renders the typed param flag's help line:
+//
+//	<param_name>, required|optional[. <fact>]...
+//
+// It leads with the canonical underscore param name (the key this flag
+// overrides in --params) and required/optional, then joins the field's facts
+// inline.
 func paramFlagUsage(f meta.Field) string {
-	return strings.Join(fieldFacts(f), ". ")
+	req := "optional"
+	if f.Required {
+		req = "required"
+	}
+	parts := append([]string{fmt.Sprintf("%s, %s", f.Name, req)}, fieldFacts(f)...)
+	return strings.Join(parts, ". ") + "."
 }
 
 // paramExample picks a concrete sample for a params-only field's --help snippet:
@@ -103,23 +103,8 @@ func sanitizeOptionDesc(s string) string { return inlineClause(s, "。；;\n\r",
 // sanitizeFieldDesc is the field-description policy: one line per field, so
 // keep full sentences and cut only at note separators (meta_data appends
 // bullet notes after ;/；) — the later sentence often carries the key
-// affordance, e.g. user_mailbox_id's `可以输入"me"`. The trailing doc
-// cross-reference is dropped first (see cutDocRef).
-func sanitizeFieldDesc(s string) string { return inlineClause(cutDocRef(s), "；;\n\r", 60) }
-
-// docRefRe matches a "see the docs" breadcrumb (更多信息参见…/获取方式见…/详见…).
-// On the compact flag line the markdown link's URL is stripped, so the
-// breadcrumb is a dead pointer — drop it. Anchored on a leading clause separator
-// so a subject that runs straight into the phrase isn't orphaned.
-var docRefRe = regexp.MustCompile(`[。；;，,、]\s*(更多信息|获取方式|获取方法|详见|[请可]?参[见考阅])`)
-
-// cutDocRef truncates s at the first doc-reference breadcrumb.
-func cutDocRef(s string) string {
-	if loc := docRefRe.FindStringIndex(s); loc != nil {
-		return s[:loc[0]]
-	}
-	return s
-}
+// affordance, e.g. user_mailbox_id's `可以输入"me"`.
+func sanitizeFieldDesc(s string) string { return inlineClause(s, "；;\n\r", 60) }
 
 // formatEnumInline renders allowed values for the help line: "v=meaning" when
 // the value carries a (sanitized, truncated) description — so opaque numeric

cmd/service/service.go

@@ -7,7 +7,6 @@ import (
 	"context"
 	"fmt"
 	"io"
-	"sort"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -65,38 +64,15 @@ func registerServiceWithContext(ctx context.Context, parent *cobra.Command, svc
 	// resource-command chain — one level for a flat dotted resource like
 	// "chat.members", deeper for genuinely nested resources. A service with no
 	// methods keeps its bare command (svcCmd is created above regardless).
-	refs := apicatalog.ServiceMethods(svc, nil)
-
-	// Collect each resource's verbs up front so resourceShort can summarize a
-	// resource as its verb list from the first ensureChildCommand call.
-	verbs := map[string][]string{}
-	for _, ref := range refs {
-		key := strings.Join(ref.ResourcePath, ".")
-		verbs[key] = append(verbs[key], ref.Method.Name)
-	}
-
-	for _, ref := range refs {
+	for _, ref := range apicatalog.ServiceMethods(svc, nil) {
 		resCmd := svcCmd
-		var path []string
 		for _, seg := range ref.ResourcePath {
-			path = append(path, seg)
-			resCmd = ensureChildCommand(resCmd, seg, resourceShort(seg, verbs[strings.Join(path, ".")]))
+			resCmd = ensureChildCommand(resCmd, seg, seg+" operations")
 		}
 		resCmd.AddCommand(buildMethodCommand(ctx, f, newMethodCommandSpec(ref), nil, parent.PersistentFlags()))
 	}
 }
 
-// resourceShort summarizes a resource as its sorted verb list, or the
-// "<name> operations" placeholder for an intermediate group with no methods.
-func resourceShort(seg string, verbs []string) string {
-	if len(verbs) == 0 {
-		return seg + " operations"
-	}
-	sorted := append([]string(nil), verbs...)
-	sort.Strings(sorted)
-	return strings.Join(sorted, ", ")
-}
-
 // serviceShort is the service command's help summary: the localized description
 // from the registry, falling back to the metadata's own description.
 func serviceShort(svc meta.Service) string {
@@ -201,19 +177,7 @@ type methodCommandSpec struct {
 	// the API declares a body.
 	acceptsBody  bool
 	declaresBody bool
-	paginates    bool   // method accepts a page_token param (so --page-all is meaningful)
-	serviceName  string // owning service name (e.g. "approval"), for the lazy affordance lookup
-}
-
-// methodPaginates reports whether a method takes a page_token param, the signal
-// that makes the --page-all/--page-limit/--page-delay flags meaningful.
-func methodPaginates(m meta.Method) bool {
-	for _, f := range m.Params() {
-		if f.Name == "page_token" {
-			return true
-		}
-	}
-	return false
+	affordance   string // rendered hand-authored usage guidance (when-to-use, examples); "" if none
 }
 
 func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
@@ -222,7 +186,6 @@ func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
 		method:       m,
 		schemaPath:   ref.SchemaPath(),
 		servicePath:  ref.Service.ServicePath,
-		serviceName:  ref.Service.Name,
 		risk:         m.Risk,
 		restricts:    m.RestrictsIdentity(),
 		identities:   m.Identities(),
@@ -230,7 +193,7 @@ func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
 		fileFields:   detectFileFields(m),
 		acceptsBody:  methodTakesBody(m.HTTPMethod),
 		declaresBody: len(m.Data()) > 0 || len(m.Files()) > 0,
-		paginates:    methodPaginates(m),
+		affordance:   renderAffordance(m),
 	}
 }
 
@@ -291,14 +254,6 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 	cmd.Flags().BoolVar(&opts.PageAll, "page-all", false, "automatically paginate through all pages")
 	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
 	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
-	// Keep the pagination flags registered (a harmless no-op if passed) but hide
-	// them from help on non-paginating commands, so help doesn't imply a
-	// get/write can paginate.
-	if !spec.paginates {
-		for _, name := range []string{"page-all", "page-limit", "page-delay"} {
-			_ = cmd.Flags().MarkHidden(name)
-		}
-	}
 	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
 	cmd.Flags().Bool("json", false, "shorthand for --format json")
 	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
@@ -316,11 +271,10 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 
 	// Registered last so the collision guard sees the standard flags above.
 	opts.binder = newParamFlagBinder(cmd, spec.params, reserved)
-	// Build-time Long; the agent guidance is added lazily by PrepareMethodHelp
-	// (setMethodHelpData records the coordinates it needs).
-	paramsOnly := opts.binder.paramsOnlyHelp()
-	cmd.Long = methodLong(m.Description, spec.schemaPath, paramsOnly)
-	setMethodHelpData(cmd, spec.serviceName, m.ID, spec.schemaPath, paramsOnly)
+	// Single composition point for Long: description, affordance, schema
+	// pointer, and the binder's params-only addendum (params whose flag name is
+	// taken, reachable via --params only).
+	cmd.Long = methodLong(m.Description, spec.affordance, spec.schemaPath, opts.binder.paramsOnlyHelp())
 
 	// Group flags for the grouped --help renderer (typed param flags are grouped
 	// as API Parameters by the binder). tagFlagGroup is a no-op for flags not
@@ -338,11 +292,13 @@ func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodComm
 	tagFlagGroup(cmd.Flags(), "file", groupBody)
 	if fl := cmd.Flags().Lookup("params"); fl != nil {
 		annotate(fl, flagGroupAnnotation, []string{groupRaw})
-		// Keep the precedence rule on the flag's own one line (not a multi-line
-		// note that breaks the one-entry-per-flag rhythm an agent parses). Only
-		// meaningful when typed flags exist to override.
+		// State the precedence rule where the agent reads it: --params is the
+		// base, typed flags override. Only meaningful when typed flags exist.
 		if len(spec.params) > 0 {
-			fl.Usage = "Raw URL/query params JSON. Supports - and @file. If both set, typed flags override matching keys in --params."
+			annotate(fl, flagNoteAnnotation, []string{
+				"Typed API parameter flags above are preferred.",
+				"If both are set, typed flags override matching keys in --params.",
+			})
 		}
 	}
 	for _, name := range []string{"as", "dry-run", "page-all", "page-limit", "page-delay", "yes"} {

cmd/whoami/whoami.go

@@ -1,169 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package whoami
-
-import (
-	"context"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/identitydiag"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// whoamiResult is the structured output of `lark-cli whoami`.
-//
-// The self-vs-delegated distinction is carried by `identity`: a bot identity is
-// the app acting as itself; a user identity is the app acting *on behalf of* a
-// person (calls are attributed to that user, who is not necessarily present).
-// onBehalfOf only *names* that person and so appears only once a user is
-// resolved — a user identity that is not signed in still has identity "user"
-// but no onBehalfOf yet. Do not read "no onBehalfOf" as "self"; read `identity`.
-type whoamiResult struct {
-	Profile        string         `json:"profile"`
-	AppID          string         `json:"appId"`
-	Brand          core.LarkBrand `json:"brand"`
-	DefaultAs      string         `json:"defaultAs"`
-	Identity       string         `json:"identity"`
-	IdentitySource string         `json:"identitySource"`
-	Available      bool           `json:"available"`
-	TokenStatus    string         `json:"tokenStatus"`
-	OnBehalfOf     *delegatedUser `json:"onBehalfOf,omitempty"`
-	Hint           string         `json:"hint,omitempty"`
-}
-
-// delegatedUser is the user a user-identity acts on behalf of.
-type delegatedUser struct {
-	UserName string `json:"userName,omitempty"`
-	OpenID   string `json:"openId,omitempty"`
-}
-
-// Options holds inputs for the whoami command.
-type Options struct {
-	Factory *cmdutil.Factory
-	As      string
-}
-
-// NewCmdWhoami creates the top-level whoami command. It reports the identity
-// that the next API call would actually use (resolved via Factory.ResolveAs),
-// together with the active profile, app, and token status. Output is always
-// JSON — whoami is consumed by agents. With the built-in credential path it is
-// local-only; when an external credential provider manages tokens, resolving
-// the identity may contact that provider.
-func NewCmdWhoami(f *cmdutil.Factory) *cobra.Command {
-	return NewCmdWhoamiWithContext(context.Background(), f)
-}
-
-// NewCmdWhoamiWithContext creates the whoami command using the build context
-// for registration-time strict-mode presentation.
-func NewCmdWhoamiWithContext(ctx context.Context, f *cmdutil.Factory) *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)
-		},
-	}
-	cmdutil.DisableAuthCheck(cmd)
-	cmdutil.AddAPIIdentityFlag(ctx, cmd, f, &opts.As)
-	// Output is always JSON. Accept (and ignore) --json so existing
-	// `whoami --json` callers don't break; hide it to avoid implying a non-JSON
-	// mode exists.
-	cmd.Flags().Bool("json", true, "deprecated: output is always JSON")
-	_ = cmd.Flags().MarkHidden("json")
-	cmdutil.SetRisk(cmd, "read")
-	return cmd
-}
-
-func whoamiRun(cmd *cobra.Command, opts *Options) error {
-	f := opts.Factory
-	cfg, err := f.Config()
-	if err != nil {
-		return err
-	}
-	ctx := cmd.Context()
-	flagAs := core.Identity(opts.As)
-	as := f.ResolveAs(ctx, cmd, flagAs)
-	// Validate as a real API call does (strict mode, then identity) so whoami
-	// can't preview an identity the next call would refuse.
-	if err := f.CheckStrictMode(ctx, as); err != nil {
-		return err
-	}
-	if err := f.CheckIdentity(as, []string{"user", "bot"}); err != nil {
-		return err
-	}
-	source := resolveSource(
-		cmd.Flags().Changed("as"),
-		flagAs,
-		f.IdentityAutoDetected,
-		f.ResolveStrictMode(ctx).ForcedIdentity(),
-	)
-	diag := identitydiag.Diagnose(ctx, f, cfg, false)
-	res := buildResult(cfg, as, source, diag)
-	output.PrintJson(f.IOStreams.Out, res)
-	return nil
-}
-
-// resolveSource derives how the effective identity became effective.
-// Mirrors Factory.ResolveAs precedence: explicit flag wins; otherwise an
-// auto-detected result means auto-detect; otherwise a strict-mode forced
-// identity means strict-mode; otherwise it came from configured default-as.
-// Values are snake_case to match the other enum fields (e.g. tokenStatus).
-func resolveSource(changedAs bool, flagAs core.Identity, autoDetected bool, strictForced core.Identity) string {
-	if changedAs && (flagAs == core.AsUser || flagAs == core.AsBot) {
-		return "flag"
-	}
-	if autoDetected {
-		return "auto_detect"
-	}
-	if strictForced != "" {
-		return "strict_mode"
-	}
-	return "default_as"
-}
-
-// buildResult maps the resolved identity and local diagnostics into the output.
-// ResolveAs only ever returns user or bot, so the default branch handles user.
-func buildResult(cfg *core.CliConfig, as core.Identity, source string, diag identitydiag.Result) *whoamiResult {
-	defaultAs := cfg.DefaultAs
-	if defaultAs == "" {
-		defaultAs = core.AsAuto
-	}
-	res := &whoamiResult{
-		Profile:        cfg.ProfileName,
-		AppID:          cfg.AppID,
-		Brand:          cfg.Brand,
-		DefaultAs:      string(defaultAs),
-		Identity:       string(as),
-		IdentitySource: source,
-	}
-	// Use the diagnosed hint as-is: it is tailored to the credential source, so
-	// it never says "auth login" when that is blocked under an external provider.
-	switch as {
-	case core.AsBot:
-		res.Available = diag.Bot.Available
-		res.TokenStatus = diag.Bot.Status
-		if !diag.Bot.Available {
-			res.Hint = diag.Bot.Hint
-		}
-	default: // user
-		res.Available = diag.User.Available
-		// Use Status (not the raw TokenStatus) so the vocab matches the bot
-		// branch: "ready" means usable for both. available stays the canonical
-		// usable signal; tokenStatus is the readable state behind it.
-		res.TokenStatus = diag.User.Status
-		// Set onBehalfOf only when a user is actually resolved; an unresolved
-		// user identity (not signed in) has no one to act on behalf of yet.
-		if diag.User.UserName != "" || diag.User.OpenID != "" {
-			res.OnBehalfOf = &delegatedUser{UserName: diag.User.UserName, OpenID: diag.User.OpenID}
-		}
-		if !diag.User.Available {
-			res.Hint = diag.User.Hint
-		}
-	}
-	return res
-}

cmd/whoami/whoami_test.go

@@ -1,320 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package whoami
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"net/http"
-	"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/identitydiag"
-)
-
-func TestResolveSource(t *testing.T) {
-	tests := []struct {
-		name         string
-		changedAs    bool
-		flagAs       core.Identity
-		autoDetected bool
-		strictForced core.Identity
-		want         string
-	}{
-		{"explicit flag user", true, core.AsUser, false, "", "flag"},
-		{"explicit flag bot", true, core.AsBot, false, "", "flag"},
-		{"flag auto falls through to auto-detect", true, core.AsAuto, true, "", "auto_detect"},
-		{"auto detected", false, "", true, "", "auto_detect"},
-		{"strict mode", false, "", false, core.AsBot, "strict_mode"},
-		{"default_as", false, "", false, "", "default_as"},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			got := resolveSource(tt.changedAs, tt.flagAs, tt.autoDetected, tt.strictForced)
-			if got != tt.want {
-				t.Errorf("resolveSource() = %q, want %q", got, tt.want)
-			}
-		})
-	}
-}
-
-func TestBuildResult_UserValid(t *testing.T) {
-	cfg := &core.CliConfig{ProfileName: "my-app", AppID: "cli_x", Brand: core.BrandLark, DefaultAs: core.AsAuto}
-	diag := identitydiag.Result{
-		User: identitydiag.Identity{Available: true, Status: "ready", TokenStatus: "valid", OpenID: "ou_x", UserName: "Alice"},
-	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
-
-	if r.Identity != "user" || r.IdentitySource != "auto_detect" {
-		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
-	}
-	// tokenStatus mirrors the unified Status vocab ("ready"), not the raw "valid".
-	if !r.Available || r.TokenStatus != "ready" {
-		t.Fatalf("available=%v status=%q", r.Available, r.TokenStatus)
-	}
-	if r.OnBehalfOf == nil || r.OnBehalfOf.OpenID != "ou_x" || r.OnBehalfOf.UserName != "Alice" {
-		t.Fatalf("onBehalfOf = %#v, want Alice/ou_x", r.OnBehalfOf)
-	}
-	if r.Hint != "" {
-		t.Fatalf("hint = %q, want empty", r.Hint)
-	}
-	if r.Profile != "my-app" || r.AppID != "cli_x" || r.Brand != core.BrandLark {
-		t.Fatalf("app context = %#v", r)
-	}
-}
-
-func TestBuildResult_UserMissingToken(t *testing.T) {
-	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandLark}
-	diag := identitydiag.Result{
-		User: identitydiag.Identity{Available: false, Status: "missing", Hint: "run: lark-cli auth login --help"}, // never logged in
-	}
-	r := buildResult(cfg, core.AsUser, "auto_detect", diag)
-
-	if r.Available {
-		t.Fatalf("available = true, want false")
-	}
-	if r.TokenStatus != "missing" {
-		t.Fatalf("tokenStatus = %q, want missing", r.TokenStatus)
-	}
-	// whoami renders the diagnosed hint verbatim (single source of truth) so it
-	// stays correct for the external-provider path without whoami knowing about it.
-	if r.Hint != diag.User.Hint {
-		t.Fatalf("hint = %q, want propagated %q", r.Hint, diag.User.Hint)
-	}
-	if r.DefaultAs != "auto" {
-		t.Fatalf("defaultAs = %q, want auto (empty normalized)", r.DefaultAs)
-	}
-}
-
-func TestBuildResult_BotReady(t *testing.T) {
-	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu, DefaultAs: core.AsBot}
-	diag := identitydiag.Result{
-		Bot: identitydiag.Identity{Available: true, Status: "ready"},
-	}
-	r := buildResult(cfg, core.AsBot, "default_as", diag)
-
-	if r.Identity != "bot" || r.IdentitySource != "default_as" {
-		t.Fatalf("identity/source = %q/%q", r.Identity, r.IdentitySource)
-	}
-	if !r.Available || r.TokenStatus != "ready" {
-		t.Fatalf("available=%v status=%q", r.Available, r.TokenStatus)
-	}
-	if r.OnBehalfOf != nil {
-		t.Fatalf("bot must not carry onBehalfOf: %#v", r.OnBehalfOf)
-	}
-	if r.Hint != "" {
-		t.Fatalf("hint = %q, want empty", r.Hint)
-	}
-}
-
-func TestBuildResult_BotNotConfigured(t *testing.T) {
-	cfg := &core.CliConfig{ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu}
-	diag := identitydiag.Result{
-		Bot: identitydiag.Identity{Available: false, Status: "not_configured", Hint: "run: lark-cli config --help"},
-	}
-	r := buildResult(cfg, core.AsBot, "auto_detect", diag)
-
-	if r.Available {
-		t.Fatalf("available = true, want false")
-	}
-	if r.TokenStatus != "not_configured" {
-		t.Fatalf("tokenStatus = %q, want not_configured", r.TokenStatus)
-	}
-	if r.Hint != diag.Bot.Hint {
-		t.Fatalf("hint = %q, want propagated %q", r.Hint, diag.Bot.Hint)
-	}
-}
-
-func TestWhoami_BotJSON(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "test-profile", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{}) // bare whoami: output is always JSON, no flag needed
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-
-	var got whoamiResult
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("json.Unmarshal() error = %v\n%s", err, stdout.String())
-	}
-	if got.Identity != "bot" {
-		t.Fatalf("identity = %q, want bot", got.Identity)
-	}
-	if !got.Available || got.TokenStatus != "ready" {
-		t.Fatalf("available=%v status=%q, want true/ready", got.Available, got.TokenStatus)
-	}
-	if got.Profile != "test-profile" {
-		t.Fatalf("profile = %q, want test-profile", got.Profile)
-	}
-	if got.IdentitySource == "" {
-		t.Fatalf("identitySource empty")
-	}
-	if got.OnBehalfOf != nil {
-		t.Fatalf("bot (self) must not carry onBehalfOf: %#v", got.OnBehalfOf)
-	}
-}
-
-func TestWhoami_RejectsInvalidAs(t *testing.T) {
-	for _, bad := range []string{"admin", "USER", "bogus123", ""} {
-		t.Run("as="+bad, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-				ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-			})
-			cmd := NewCmdWhoami(f)
-			cmd.SetArgs([]string{"--as", bad})
-			err := cmd.Execute()
-			if err == nil {
-				t.Fatalf("Execute() with --as %q = nil, want validation error", bad)
-			}
-			// Lock in the typed validation contract: an unsupported identity must
-			// surface as a *errs.ValidationError on --as, not just any error.
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("Execute() with --as %q: error type = %T, want *errs.ValidationError: %v", bad, err, err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-			}
-			if ve.Param != "--as" {
-				t.Errorf("Param = %q, want %q", ve.Param, "--as")
-			}
-		})
-	}
-}
-
-func TestWhoami_ConfigErrorPropagates(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	wantErr := fmt.Errorf("boom")
-	f.Config = func() (*core.CliConfig, error) { return nil, wantErr }
-
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{"--json"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatalf("Execute() error = nil, want propagated config error")
-	}
-	// The f.Config() failure must propagate unchanged, not be masked by a later
-	// command-execution error.
-	if !errors.Is(err, wantErr) {
-		t.Fatalf("Execute() error = %v, want it to wrap %v", err, wantErr)
-	}
-}
-
-func TestWhoami_StrictModeRejectsCrossIdentity(t *testing.T) {
-	// Bot-only account → strict mode bot. A real `--as user` call would be
-	// rejected by CheckStrictMode; whoami must reject it identically rather than
-	// previewing a user identity the next call would refuse.
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
-		ProfileName: "p", AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-		SupportedIdentities: 2, // bot only
-	})
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{"--as", "user", "--json"})
-	err := cmd.Execute()
-	if err == nil {
-		t.Fatalf("Execute() with --as user under strict bot = nil, want strict-mode rejection")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("error type = %T, want *errs.ValidationError: %v", err, err)
-	}
-}
-
-type fakeExtProvider struct {
-	name    string
-	account *extcred.Account
-}
-
-func (p *fakeExtProvider) Name() string { return p.name }
-func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
-	return p.account, nil
-}
-func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
-	return nil, nil // no UAT served locally; whoami runs with verify=false
-}
-
-func externalWhoamiFactory(cfg *core.CliConfig) (*cmdutil.Factory, *bytes.Buffer) {
-	cred := credential.NewCredentialProvider(
-		[]extcred.Provider{&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: cfg.AppID}}},
-		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{}},
-	}
-	return f, out
-}
-
-// Regression for the external-provider blind spot: with credentials managed by
-// an extension provider, a signed-in user must read as available, and an
-// unavailable identity must not be told to "auth login" (which is blocked).
-func TestWhoami_ExternalProvider_UserReady(t *testing.T) {
-	cfg := &core.CliConfig{
-		ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu,
-		SupportedIdentities: uint8(extcred.SupportsAll), UserOpenId: "ou_x", UserName: "Alice",
-	}
-	f, out := externalWhoamiFactory(cfg)
-
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{"--as", "user", "--json"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-	var got whoamiResult
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("Unmarshal: %v\n%s", err, out.String())
-	}
-	if got.Identity != "user" || !got.Available || got.TokenStatus != "ready" {
-		t.Fatalf("got %#v, want user/available/ready", got)
-	}
-	if got.OnBehalfOf == nil || got.OnBehalfOf.UserName != "Alice" || got.OnBehalfOf.OpenID != "ou_x" {
-		t.Fatalf("onBehalfOf = %#v, want Alice/ou_x (delegated)", got.OnBehalfOf)
-	}
-	if got.Hint != "" {
-		t.Fatalf("hint = %q, want empty when available", got.Hint)
-	}
-}
-
-func TestWhoami_ExternalProvider_UserHintNotKeychain(t *testing.T) {
-	cfg := &core.CliConfig{
-		ProfileName: "p", AppID: "cli_x", Brand: core.BrandFeishu,
-		SupportedIdentities: uint8(extcred.SupportsUser), // user supported but not signed in
-	}
-	f, out := externalWhoamiFactory(cfg)
-
-	cmd := NewCmdWhoami(f)
-	cmd.SetArgs([]string{"--as", "user", "--json"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("Execute() error = %v", err)
-	}
-	var got whoamiResult
-	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
-		t.Fatalf("Unmarshal: %v\n%s", err, out.String())
-	}
-	if got.Identity != "user" || got.Available {
-		t.Fatalf("got identity=%q available=%v, want user/false", got.Identity, got.Available)
-	}
-	if strings.Contains(got.Hint, "auth login") {
-		t.Fatalf("hint must not point at auth login under external provider: %q", got.Hint)
-	}
-	if !strings.Contains(got.Hint, "external") {
-		t.Fatalf("hint should explain external management: %q", got.Hint)
-	}
-}

content_embed.go

@@ -1,41 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package main
-
-import (
-	"embed"
-	"fmt"
-	"io/fs"
-	"os"
-
-	"github.com/larksuite/cli/cmd"
-	"github.com/larksuite/cli/internal/affordance"
-)
-
-// embeddedContentFS bundles the agent-readable content that must ship in lockstep
-// with the binary: each skill's docs (SKILL.md + references/, plus whiteboard's
-// routes/ and scenes/) and the per-domain affordance guidance (affordance/*.md).
-// Machine-resource skill dirs (assets/, scripts/) are excluded. It's a whitelist —
-// a new content type is omitted until added to the embed list. The embed must live
-// in this root package because go:embed cannot reach up out of a package's dir.
-//
-//go:embed skills/*/SKILL.md skills/*/references skills/*/routes skills/*/scenes affordance/*.md
-var embeddedContentFS embed.FS
-
-// init wires the embedded content into the CLI. It compiles into `go build .` but
-// not the single-file preview build (`go build ./main.go`), so that build stays
-// self-contained (shipping no embedded content). Assembly failures warn on stderr
-// rather than panicking — embedded content is nice-to-have, not load-bearing.
-func init() {
-	if sub, err := fs.Sub(embeddedContentFS, "skills"); err != nil {
-		fmt.Fprintln(os.Stderr, "warning: skills embed assembly failed, skills commands disabled:", err)
-	} else {
-		cmd.SetEmbeddedSkillContent(sub)
-	}
-	if sub, err := fs.Sub(embeddedContentFS, "affordance"); err != nil {
-		fmt.Fprintln(os.Stderr, "warning: affordance embed assembly failed, command guidance disabled:", err)
-	} else {
-		affordance.SetSource(sub)
-	}
-}

docs/superpowers/specs/2026-07-02-create-svglide-codex-runtime-design.md

@@ -1,259 +0,0 @@
-# `slides +create-svglide` Codex Runtime Design
-
-Date: 2026-07-02
-Branch: `feat-svglide-07`
-Scope: first local-only version of `lark-cli slides +create-svglide`
-
-## Result
-
-Build `slides +create-svglide` as a staged local runtime for AnyGen SVG Slides. The command creates and manages a run directory that Codex can fill with generated content, assets, and SVG slides. The CLI owns state, prompts, schemas, validation, preview, receipts, and recovery. Codex owns LLM reasoning, web research, image/search execution, chart design, and SVG authoring.
-
-The first version does not publish to Feishu Slides. It must produce a local, inspectable SVG deck workbench.
-
-## Context
-
-`feat-svglide-07` currently starts from the latest `origin/main` and has only the existing Slides XML shortcut surface. There is no current `+create-svglide` implementation on this branch.
-
-The AnyGen SVG Slides prompt should be reused as contracts and workflow rules, not pasted as one large prompt. Its value is split across request interpretation, research, design brief, outline, `slide_content.md`, asset planning, SVG authoring, protocol validation, preview, and repair.
-
-## Goals
-
-- Add a staged `slides +create-svglide` command group.
-- Create a local run directory under a user-specified `--out` path, usually `.lark-slides/svglide-runs/<run-id>`.
-- Generate prompt task files that tell Codex exactly what to produce for each stage.
-- Generate JSON schemas for stage outputs.
-- Track stage state in `run.json`.
-- Validate JSON outputs, SVG protocol basics, asset href existence, slide count, placeholder slides, and preview generation.
-- Generate `preview.html` for local inspection.
-- Write receipts and `repair_queue.md` so failed runs can resume from the current stage.
-
-## Non-Goals
-
-- No online Feishu Slides creation.
-- No `slide_engine` or `slide` server changes.
-- No SVG-to-SXSD conversion.
-- No built-in model API provider.
-- No built-in web search, image generation, or image search client.
-- No complete 12-agent process runner.
-- No PPTX import/edit workflow.
-
-## Command Surface
-
-```bash
-lark-cli slides +create-svglide init --title "Demo" --input ./source.md --audience "..." --delivery-mode self_read --pages 8 --out ./.lark-slides/svglide-runs/demo
-lark-cli slides +create-svglide next <run-dir>
-lark-cli slides +create-svglide status <run-dir>
-lark-cli slides +create-svglide validate <run-dir>
-lark-cli slides +create-svglide preview <run-dir>
-```
-
-`init` creates the run directory, writes the initial request files, schemas, stage prompts, and `run.json`.
-
-`next` reads `run.json`, finds the next stage, verifies required inputs, renders or refreshes that stage's Codex task prompt, and reports the exact files Codex must create. It must not pretend LLM work is complete.
-
-`status` checks declared outputs and receipts for each stage, then prints the current stage, missing files, and next useful command.
-
-`validate` runs deterministic checks and writes validation receipts.
-
-`preview` writes `preview.html` from `outline/deck.json` and `slides/*.svg`.
-
-## Run Directory Contract
-
-```text
-<run-dir>/
-  run.json
-  README.md
-  request/request.json
-  request/source_manifest.json
-  research/research_notes.md
-  research/sources.json
-  brief/design_brief.json
-  brief/visual_system.json
-  outline/deck.json
-  content/slide_content.md
-  content/slide_content.json
-  assets/assets_plan.json
-  assets/images/
-  assets/charts/
-  slides/*.svg
-  prompts/*.task.md
-  schemas/*.schema.json
-  receipts/*.json
-  receipts/generation_summary.md
-  repair_queue.md
-  preview.html
-```
-
-The run directory is local agent state. It should not be committed by default.
-
-## State Model
-
-`run.json` stores:
-
-- version
-- runtime, always `codex` in v1
-- command name
-- title
-- created and updated timestamps
-- current stage
-- stage list with status, inputs, outputs, and receipt path
-- important artifact paths
-- policy flags: `publish_enabled=false`, `network_by_codex=true`, `image_generation_by_codex=true`, `overwrite=false`
-
-Stage statuses:
-
-```text
-pending
-ready
-in_progress
-done
-failed
-blocked
-needs_repair
-```
-
-## Stage Design
-
-### 1. request
-
-Role: Request Interpreter
-
-Input: CLI flags and local source path.
-
-Output: `request/request.json`, `request/source_manifest.json`.
-
-Validation: title, audience, delivery mode, page count, and source references must be explicit or marked missing.
-
-### 2. research
-
-Role: Researcher
-
-Input: request files and source files.
-
-Output: `research/research_notes.md`, `research/sources.json`.
-
-Validation: key facts need source references. Codex may perform web research, but the CLI only validates resulting files.
-
-### 3. design_brief
-
-Role: Design Brief Resolver and Visual System Planner
-
-Input: request and research outputs.
-
-Output: `brief/design_brief.json`, `brief/visual_system.json`.
-
-Validation: narrative spine, depth, tone, and visual system dimensions must be present.
-
-### 4. outline
-
-Role: Outline Planner
-
-Input: design brief.
-
-Output: `outline/deck.json`.
-
-Validation: page count matches request; each slide has id, title, summary, role, and key message.
-
-### 5. slide_content
-
-Role: Content Builder
-
-Input: deck outline and research notes.
-
-Output: `content/slide_content.md`, `content/slide_content.json`.
-
-Validation: every slide has key material, content blocks, and source notes. This is content planning, not final layout.
-
-### 6. assets
-
-Role: Asset Planner and Chart Generator
-
-Input: slide content and visual system.
-
-Output: `assets/assets_plan.json`, optional `assets/images/*`, optional `assets/charts/*.svg`.
-
-Validation: every planned asset has purpose plus either a local path or a fallback. Chart takeaway must be written before chart type.
-
-### 7. svg_author
-
-Role: SVG Author
-
-Input: deck, slide content, visual system, and assets.
-
-Output: `slides/*.svg`.
-
-Validation: each slide must contain more than a background. Each slide needs a background, title, visible content or visual element, semantic id, and valid SVG root.
-
-### 8. validate_preview_repair
-
-Role: Protocol Validator, Preview Agent, and Repair Agent
-
-Input: generated slides.
-
-Output: `receipts/lint.json`, `receipts/preview.json`, `repair_queue.md`, `preview.html`.
-
-Validation: SVG protocol lint, local href checks, slide count match, preview write success, and unresolved issues recorded in the repair queue.
-
-## Code Layout
-
-```text
-shortcuts/slides/
-  slides_create_svglide.go
-  slides_create_svglide_test.go
-
-internal/svglide/
-  run.go
-  init.go
-  stage.go
-  prompt.go
-  schema.go
-  validate.go
-  preview.go
-  receipt.go
-```
-
-The shortcut package should stay thin. State, prompt rendering, validation, and preview logic belong in `internal/svglide` so they can be tested without a Cobra/runtime-heavy command harness.
-
-## Skill Documentation
-
-Update `skills/lark-slides/SKILL.md` and add a focused reference file for the local SVG runtime. The skill should explain that `+create-svglide` is local-only in v1, requires Codex to fill stage outputs, and must not be described as an online publish path.
-
-## Error Handling
-
-- Missing required inputs block the stage and write a receipt.
-- Invalid JSON or schema mismatch marks the stage failed.
-- Invalid SVG marks `needs_repair` and writes `repair_queue.md`.
-- Existing output paths are not overwritten unless an explicit overwrite policy is enabled.
-- Partially completed stages remain inspectable; reruns resume from the current stage.
-
-## Tests
-
-Unit tests:
-
-- `init` creates the expected directory tree and `run.json`.
-- `init` refuses to overwrite an existing run directory by default.
-- `status` identifies missing outputs.
-- `next` renders the correct stage prompt and does not mark Codex-only stages done.
-- `validate` catches invalid SVG, missing hrefs, placeholder slides, and slide count mismatch.
-- `preview` writes HTML that references generated SVG files.
-
-Fixtures:
-
-- `testdata/svglide_run_valid/`
-- `testdata/svglide_run_invalid/`
-
-No live end-to-end test is required for v1 because this version does not call Feishu APIs.
-
-## Acceptance Criteria
-
-- A user can initialize a run directory from local input.
-- Codex can follow generated task prompts stage by stage.
-- The CLI can report status and missing artifacts.
-- The CLI can validate a completed local SVG deck.
-- The CLI can generate local preview HTML.
-- Failed validation produces actionable repair output.
-- No online presentation is created.
-
-## Further Judgment
-
-This design deliberately optimizes for artifact contracts rather than agent-count symmetry. Once the local runtime is stable, individual stages can be split into fuller agents without changing the run directory contract.

docs/vendor/anygen-svg/source.meta.json

@@ -1,8 +0,0 @@
-{
-  "doc_url": "https://bytedance.larkoffice.com/docx/KnCLd7xr5ohWONxhKsncZ3Lxnvd",
-  "local_full_snapshot": "/Users/bytedance/Documents/Codex/2026-07-01/https-bytedance-larkoffice-com-docx-kncld7xr5ohwonxhksncz3lxnvd/outputs/lark_doc_KnCLd7xr5ohWONxhKsncZ3Lxnvd/full.md",
-  "local_handoff": "/Users/bytedance/Documents/Codex/2026-07-01/https-bytedance-larkoffice-com-docx-kncld7xr5ohwonxhksncz3lxnvd/outputs/anygen-slides-svg-prompt-handoff.md",
-  "fetched_by": "local export",
-  "fetched_for": "slides +create-svglide AnyGen SVG prompt runtime experiment",
-  "experiment_mode": "experiment_unrestricted_assets"
-}

docs/vendor/anygen-svg/source.outline.md

@@ -1,20 +0,0 @@
-# AnyGen SVG Slides Local Outline
-
-Source full snapshot: `docs/vendor/anygen-svg/source.full.md`
-Source handoff: `/Users/bytedance/Documents/Codex/2026-07-01/https-bytedance-larkoffice-com-docx-kncld7xr5ohwonxhksncz3lxnvd/outputs/anygen-slides-svg-prompt-handoff.md`
-Remote doc: `https://bytedance.larkoffice.com/docx/KnCLd7xr5ohWONxhKsncZ3Lxnvd`
-
-Required sections to split:
-
-- System prompt（编排 / mode_system_prompt_svg）
-- SVG reference（协议 schema + 设计规范 / svg_reference）
-- resolve_design_brief
-- slide_outline
-- activate_slides_edit
-- slides_edit
-- finish_slides_edit
-- slide_organize
-- compute_custom_shape_bbox
-- generate_svg_chart
-- slides_convert
-- slides_parse_template

errs/types_test.go

@@ -319,7 +319,7 @@ func TestPermissionError_FullChain(t *testing.T) {
 		WithHint("run: lark-cli auth login --scope %q", "mail:user_mailbox.message:send").
 		WithMissingScopes("mail:user_mailbox.message:send").
 		WithIdentity("user").
-		WithConsoleURL("https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=mail:user_mailbox.message:send")
+		WithConsoleURL("https://open.feishu.cn/app/cli_xxx/auth")
 
 	if got.Category != errs.CategoryAuthorization {
 		t.Errorf("Category = %q, want %q", got.Category, errs.CategoryAuthorization)
@@ -419,7 +419,7 @@ func TestBuilder_WireFormat(t *testing.T) {
 		WithHint("run lark-cli auth login --scope calendar:event:create").
 		WithMissingScopes("calendar:event:create").
 		WithIdentity("user").
-		WithConsoleURL("https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=calendar:event:create")
+		WithConsoleURL("https://open.feishu.cn/app/cli_xxx/auth")
 
 	buf, err := json.Marshal(e)
 	if err != nil {
@@ -439,7 +439,7 @@ func TestBuilder_WireFormat(t *testing.T) {
 		"hint":           "run lark-cli auth login --scope calendar:event:create",
 		"log_id":         "20260520-0a1b2c3d",
 		"identity":       "user",
-		"console_url":    "https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=calendar:event:create",
+		"console_url":    "https://open.feishu.cn/app/cli_xxx/auth",
 		"missing_scopes": []any{"calendar:event:create"},
 	}
 	for k, want := range wantFields {

events/im/card_action.go

@@ -1,132 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-// CardActionTriggerOutput is the flattened shape for card.action.trigger.
-type CardActionTriggerOutput struct {
-	Type        string `json:"type"                    desc:"Event type; always card.action.trigger"`
-	EventID     string `json:"event_id,omitempty"      desc:"Globally unique event ID"`
-	Timestamp   string `json:"timestamp,omitempty"     desc:"Event delivery time (ms timestamp string)" kind:"timestamp_ms"`
-	OperatorID  string `json:"operator_id,omitempty"   desc:"Operator open_id"                          kind:"open_id"`
-	MessageID   string `json:"message_id,omitempty"    desc:"Message ID of the card"                    kind:"message_id"`
-	ChatID      string `json:"chat_id,omitempty"       desc:"Chat ID"                                   kind:"chat_id"`
-	Host        string `json:"host,omitempty"          desc:"Host type: im_message / im_top_notice"`
-	Token       string `json:"token,omitempty"         desc:"Token for delay card update (valid 30 min, max 2 updates)"`
-	ActionTag   string `json:"action_tag,omitempty"    desc:"Triggered element type: button/select_static/input/checker/etc"`
-	ActionValue string `json:"action_value,omitempty"  desc:"Developer-defined action value as JSON string"`
-	ActionName  string `json:"action_name,omitempty"   desc:"Element name attribute"`
-	FormValue   string `json:"form_value,omitempty"    desc:"Form submission values as JSON string (only on form submit)"`
-	InputValue  string `json:"input_value,omitempty"   desc:"Input field value (only for input elements)"`
-	Option      string `json:"option,omitempty"        desc:"Selected option value (for single-select dropdown)"`
-	Options     string `json:"options,omitempty"       desc:"Selected options, comma-separated (for multi-select)"`
-	Checked     bool   `json:"checked"                 desc:"Checkbox state (for checkbox elements)"`
-	Timezone    string `json:"timezone,omitempty"      desc:"User timezone for date/time picker interactions"`
-	CardContent string `json:"card_content,omitempty"  desc:"Original card JSON content (body.content) auto-fetched via message get API at consume time using message_id; empty if message_id absent or fetch fails"`
-}
-
-func processCardAction(ctx context.Context, rt event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
-	var envelope struct {
-		Header struct {
-			EventID    string `json:"event_id"`
-			EventType  string `json:"event_type"`
-			CreateTime string `json:"create_time"`
-		} `json:"header"`
-		Event struct {
-			Operator struct {
-				OpenID string `json:"open_id"`
-			} `json:"operator"`
-			Token  string `json:"token"`
-			Host   string `json:"host"`
-			Action struct {
-				Tag        string                 `json:"tag"`
-				Value      map[string]interface{} `json:"value"`
-				Name       string                 `json:"name"`
-				FormValue  map[string]interface{} `json:"form_value"`
-				InputValue string                 `json:"input_value"`
-				Option     string                 `json:"option"`
-				Options    []string               `json:"options"`
-				Checked    bool                   `json:"checked"`
-				Timezone   string                 `json:"timezone"`
-			} `json:"action"`
-			Context struct {
-				OpenMessageID string `json:"open_message_id"`
-				OpenChatID    string `json:"open_chat_id"`
-			} `json:"context"`
-		} `json:"event"`
-	}
-	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
-		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload
-	}
-
-	actionValue := marshalToString(envelope.Event.Action.Value)
-	formValue := marshalToString(envelope.Event.Action.FormValue)
-	options := strings.Join(envelope.Event.Action.Options, ",")
-
-	out := &CardActionTriggerOutput{
-		Type:        envelope.Header.EventType,
-		EventID:     envelope.Header.EventID,
-		Timestamp:   envelope.Header.CreateTime,
-		OperatorID:  envelope.Event.Operator.OpenID,
-		MessageID:   envelope.Event.Context.OpenMessageID,
-		ChatID:      envelope.Event.Context.OpenChatID,
-		Host:        envelope.Event.Host,
-		Token:       envelope.Event.Token,
-		ActionTag:   envelope.Event.Action.Tag,
-		ActionValue: actionValue,
-		ActionName:  envelope.Event.Action.Name,
-		FormValue:   formValue,
-		InputValue:  envelope.Event.Action.InputValue,
-		Option:      envelope.Event.Action.Option,
-		Options:     options,
-		Checked:     envelope.Event.Action.Checked,
-		Timezone:    envelope.Event.Action.Timezone,
-	}
-
-	if out.MessageID != "" && rt != nil {
-		out.CardContent = fetchCardUserDSL(ctx, rt, out.MessageID)
-	}
-
-	return json.Marshal(out)
-}
-
-// fetchCardUserDSL gets the card message content via message get API.
-// Returns empty string on any failure — never blocks event consumption.
-func fetchCardUserDSL(ctx context.Context, rt event.APIClient, messageID string) string {
-	path := "/open-apis/im/v1/messages/" + messageID + "?card_msg_content_type=user_card_content"
-	resp, err := rt.CallAPI(ctx, "GET", path, nil)
-	if err != nil {
-		return ""
-	}
-	var result struct {
-		Code int    `json:"code"`
-		Msg  string `json:"msg"`
-		Data struct {
-			Items []struct {
-				Body struct {
-					Content string `json:"content"`
-				} `json:"body"`
-			} `json:"items"`
-		} `json:"data"`
-	}
-	if json.Unmarshal(resp, &result) != nil || result.Code != 0 || len(result.Data.Items) == 0 {
-		return ""
-	}
-	return result.Data.Items[0].Body.Content
-}
-
-func marshalToString(m map[string]interface{}) string {
-	if len(m) == 0 {
-		return ""
-	}
-	b, _ := json.Marshal(m)
-	return string(b)
-}

events/im/card_action_test.go

@@ -1,432 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-func TestCardActionTriggerRegistered(t *testing.T) {
-	def, ok := event.Lookup("card.action.trigger")
-	if !ok {
-		t.Fatal("card.action.trigger should be registered via Keys()")
-	}
-	if def.Schema.Custom == nil {
-		t.Error("card.action.trigger must set Schema.Custom")
-	}
-	if def.Process == nil {
-		t.Error("card.action.trigger must set Process")
-	}
-	if len(def.Scopes) == 0 {
-		t.Error("Scopes must not be empty")
-	}
-}
-
-func TestProcessCardAction_Button(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_btn_001",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469273"
-		},
-		"event": {
-			"operator": {"open_id": "ou_operator"},
-			"token": "c-token-btn",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {"key": "approve"},
-				"name": "approve_btn",
-				"form_value": {},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_msg_001",
-				"open_chat_id": "oc_chat_001"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.Type != "card.action.trigger" {
-		t.Errorf("Type = %q, want card.action.trigger", out.Type)
-	}
-	if out.EventID != "ev_btn_001" {
-		t.Errorf("EventID = %q", out.EventID)
-	}
-	if out.OperatorID != "ou_operator" {
-		t.Errorf("OperatorID = %q", out.OperatorID)
-	}
-	if out.ActionTag != "button" {
-		t.Errorf("ActionTag = %q, want button", out.ActionTag)
-	}
-	if out.ActionValue != `{"key":"approve"}` {
-		t.Errorf("ActionValue = %q", out.ActionValue)
-	}
-	if out.ActionName != "approve_btn" {
-		t.Errorf("ActionName = %q", out.ActionName)
-	}
-	if out.Token != "c-token-btn" {
-		t.Errorf("Token = %q", out.Token)
-	}
-	if out.MessageID != "om_msg_001" {
-		t.Errorf("MessageID = %q", out.MessageID)
-	}
-	if out.ChatID != "oc_chat_001" {
-		t.Errorf("ChatID = %q", out.ChatID)
-	}
-	if out.Host != "im_message" {
-		t.Errorf("Host = %q", out.Host)
-	}
-	if out.Timestamp != "1776409469273" {
-		t.Errorf("Timestamp = %q", out.Timestamp)
-	}
-}
-
-func TestProcessCardAction_FormSubmit(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_form_001",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469274"
-		},
-		"event": {
-			"operator": {"open_id": "ou_form_user"},
-			"token": "c-token-form",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {},
-				"name": "submit_btn",
-				"form_value": {"name": "test-user", "reason": "testing"},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_form_001",
-				"open_chat_id": "oc_chat_002"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.FormValue != `{"name":"test-user","reason":"testing"}` {
-		t.Errorf("FormValue = %q", out.FormValue)
-	}
-	if out.ActionTag != "button" {
-		t.Errorf("ActionTag = %q, want button", out.ActionTag)
-	}
-}
-
-func TestProcessCardAction_MultiSelect(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_ms_001",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469275"
-		},
-		"event": {
-			"operator": {"open_id": "ou_ms_user"},
-			"token": "c-token-ms",
-			"host": "im_message",
-			"action": {
-				"tag": "multi_select_static",
-				"value": {},
-				"name": "multi_select",
-				"options": ["opt_1", "opt_3"],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_ms_001",
-				"open_chat_id": "oc_chat_003"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.Options != "opt_1,opt_3" {
-		t.Errorf("Options = %q, want opt_1,opt_3", out.Options)
-	}
-	if out.ActionTag != "multi_select_static" {
-		t.Errorf("ActionTag = %q", out.ActionTag)
-	}
-}
-
-func TestProcessCardAction_Input(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_input_001",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469276"
-		},
-		"event": {
-			"operator": {"open_id": "ou_input_user"},
-			"token": "c-token-input",
-			"host": "im_message",
-			"action": {
-				"tag": "input",
-				"value": {},
-				"name": "text_input",
-				"input_value": "hello world",
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_input_001",
-				"open_chat_id": "oc_chat_004"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.InputValue != "hello world" {
-		t.Errorf("InputValue = %q", out.InputValue)
-	}
-	if out.ActionTag != "input" {
-		t.Errorf("ActionTag = %q", out.ActionTag)
-	}
-}
-
-func TestProcessCardAction_DatePicker(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_date_001",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469277"
-		},
-		"event": {
-			"operator": {"open_id": "ou_date_user"},
-			"token": "c-token-date",
-			"host": "im_message",
-			"action": {
-				"tag": "date_picker",
-				"value": {},
-				"name": "date_selector",
-				"option": "2024-04-01 +0800",
-				"timezone": "Asia/Shanghai",
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_date_001",
-				"open_chat_id": "oc_chat_005"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.Option != "2024-04-01 +0800" {
-		t.Errorf("Option = %q", out.Option)
-	}
-	if out.Timezone != "Asia/Shanghai" {
-		t.Errorf("Timezone = %q", out.Timezone)
-	}
-}
-
-func TestProcessCardAction_MalformedPayload(t *testing.T) {
-	raw := &event.RawEvent{
-		EventID:   "ev_bad",
-		EventType: "card.action.trigger",
-		Payload:   json.RawMessage(`not json`),
-		Timestamp: time.Now(),
-	}
-	got, err := processCardAction(context.Background(), nil, raw, nil)
-	if err != nil {
-		t.Fatalf("Process should swallow parse errors, got %v", err)
-	}
-	if string(got) != "not json" {
-		t.Errorf("malformed fallback output = %q, want original bytes", string(got))
-	}
-}
-
-func TestProcessCardAction_MessageGetSuccess(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_mg_ok",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469278"
-		},
-		"event": {
-			"operator": {"open_id": "ou_mg_user"},
-			"token": "c-token-mg",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {"key": "click"},
-				"name": "btn",
-				"form_value": {},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_mg_001",
-				"open_chat_id": "oc_chat_mg"
-			}
-		}
-	}`
-	cardContent := `{"header":{"title":{"tag":"plain_text","content":"A card"}}}`
-	mock := &mockAPIClient{resp: `{
-		"code": 0,
-		"msg": "success",
-		"data": {
-			"items": [{
-				"body": {"content": "` + escapeJSON(cardContent) + `"}
-			}]
-		}
-	}`}
-	out := runCardAction(t, payload, mock)
-
-	if out.CardContent == "" {
-		t.Error("CardContent should not be empty when message get succeeds")
-	}
-}
-
-func TestProcessCardAction_MessageGetErrorCode(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_mg_ec",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469279"
-		},
-		"event": {
-			"operator": {"open_id": "ou_mg_user2"},
-			"token": "c-token-mg2",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {},
-				"name": "btn",
-				"form_value": {},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_mg_002",
-				"open_chat_id": "oc_chat_mg2"
-			}
-		}
-	}`
-	mock := &mockAPIClient{resp: `{"code": 1, "msg": "error", "data": {"items": []}}`}
-	out := runCardAction(t, payload, mock)
-
-	if out.CardContent != "" {
-		t.Errorf("CardContent should be empty when code != 0, got %q", out.CardContent)
-	}
-}
-
-func TestProcessCardAction_MessageGetFailure(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_mg_fail",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469280"
-		},
-		"event": {
-			"operator": {"open_id": "ou_mg_user3"},
-			"token": "c-token-mg3",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {},
-				"name": "btn",
-				"form_value": {},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "om_mg_003",
-				"open_chat_id": "oc_chat_mg3"
-			}
-		}
-	}`
-	mock := &mockAPIClient{errResp: true}
-	out := runCardAction(t, payload, mock)
-
-	if out.CardContent != "" {
-		t.Errorf("CardContent should be empty when message get fails, got %q", out.CardContent)
-	}
-}
-
-func TestProcessCardAction_EmptyMessageID(t *testing.T) {
-	payload := `{
-		"schema": "2.0",
-		"header": {
-			"event_id": "ev_no_msg",
-			"event_type": "card.action.trigger",
-			"create_time": "1776409469281"
-		},
-		"event": {
-			"operator": {"open_id": "ou_no_msg"},
-			"token": "c-token-nm",
-			"host": "im_message",
-			"action": {
-				"tag": "button",
-				"value": {},
-				"name": "btn",
-				"form_value": {},
-				"options": [],
-				"checked": false
-			},
-			"context": {
-				"open_message_id": "",
-				"open_chat_id": "oc_chat_nm"
-			}
-		}
-	}`
-	out := runCardAction(t, payload, nil)
-
-	if out.CardContent != "" {
-		t.Errorf("CardContent should be empty when message_id is absent, got %q", out.CardContent)
-	}
-}
-
-type mockAPIClient struct {
-	resp    string
-	errResp bool
-}
-
-func (m *mockAPIClient) CallAPI(_ context.Context, _, _ string, _ interface{}) (json.RawMessage, error) {
-	if m.errResp {
-		return nil, context.DeadlineExceeded
-	}
-	return json.RawMessage(m.resp), nil
-}
-
-func runCardAction(t *testing.T, payload string, rt event.APIClient) CardActionTriggerOutput {
-	t.Helper()
-	raw := &event.RawEvent{
-		EventID:   "ev_test",
-		EventType: "card.action.trigger",
-		Payload:   json.RawMessage(payload),
-		Timestamp: time.Now(),
-	}
-	got, err := processCardAction(context.Background(), rt, raw, nil)
-	if err != nil {
-		t.Fatalf("Process error: %v", err)
-	}
-	var out CardActionTriggerOutput
-	if err := json.Unmarshal(got, &out); err != nil {
-		t.Fatalf("Process output is not valid CardActionTriggerOutput JSON: %v\nraw=%s", err, string(got))
-	}
-	return out
-}
-
-func escapeJSON(s string) string {
-	b, _ := json.Marshal(s)
-	return string(b[1 : len(b)-1])
-}

events/im/register.go

@@ -27,21 +27,6 @@ func Keys() []event.KeyDefinition {
 			AuthTypes:             []string{"bot"},
 			RequiredConsoleEvents: []string{"im.message.receive_v1"},
 		},
-		{
-			Key:              "card.action.trigger",
-			DisplayName:      "Card action",
-			Description:      "Triggered when a user interacts with an interactive card (button click, form submit, dropdown select, etc.). Output includes: token (valid 30 min, max 2 updates), action details (tag, value, name, form_value), and card_content (original card in userDSL text format, auto-fetched at consume time). To update the card: parse card_content to understand the current state, construct the new card JSON, then call `lark-cli api POST /open-apis/interactive/v1/card/update` with the token (see lark-im-card-action-reply.md).",
-			EventType:        "card.action.trigger",
-			SubscriptionType: event.SubTypeCallback,
-			Schema: event.SchemaDef{
-				Custom: &event.SchemaSpec{Type: reflect.TypeOf(CardActionTriggerOutput{})},
-			},
-			Process:               processCardAction,
-			Scopes:                []string{"im:message:readonly"},
-			AuthTypes:             []string{"bot"},
-			SingleConsumer:        true,
-			RequiredConsoleEvents: []string{"card.action.trigger"},
-		},
 	}
 
 	for _, rk := range nativeIMKeys {

events/register.go

@@ -7,7 +7,6 @@ package events
 import (
 	"github.com/larksuite/cli/events/im"
 	"github.com/larksuite/cli/events/minutes"
-	"github.com/larksuite/cli/events/task"
 	"github.com/larksuite/cli/events/vc"
 	"github.com/larksuite/cli/events/whiteboard"
 	"github.com/larksuite/cli/internal/event"
@@ -18,7 +17,6 @@ func init() {
 	all := [][]event.KeyDefinition{
 		im.Keys(),
 		minutes.Keys(),
-		task.Keys(),
 		vc.Keys(),
 		whiteboard.Keys(),
 	}

events/task/native.go

@@ -1,23 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package task
-
-// TaskUpdateUserAccessV2Data is the Task v2 update event payload under the
-// standard Lark V2 event envelope.
-type TaskUpdateUserAccessV2Data struct {
-	EventTypes []string `json:"event_types,omitempty" desc:"Task commit types included in this event" enum:"task_create,task_deleted,task_summary_update,task_desc_update,task_assignees_update,task_followers_update,task_reminders_update,task_start_due_update,task_completed_update"`
-	TaskGUID   string   `json:"task_guid,omitempty" desc:"Task GUID that changed" kind:"task_guid"`
-}
-
-var taskUpdateUserAccessCommitTypes = []string{
-	"task_create",
-	"task_deleted",
-	"task_summary_update",
-	"task_desc_update",
-	"task_assignees_update",
-	"task_followers_update",
-	"task_reminders_update",
-	"task_start_due_update",
-	"task_completed_update",
-}

events/task/preconsume.go

@@ -1,32 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package task
-
-import (
-	"context"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/event"
-)
-
-const taskSubscriptionPath = "/open-apis/task/v2/task_v2/task_subscription?user_id_type=open_id"
-
-func taskSubscriptionPreConsume(ctx context.Context, rt event.APIClient, _ map[string]string) (func() error, error) {
-	if rt == nil {
-		return nil, errs.NewInternalError(errs.SubtypeUnknown,
-			"runtime API client is required for pre-consume subscription")
-	}
-
-	if _, err := rt.CallAPI(ctx, "POST", taskSubscriptionPath, nil); err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(
-			errs.SubtypeNetworkTransport,
-			"failed to subscribe task event",
-		).WithCause(err)
-	}
-
-	return nil, nil
-}

events/task/preconsume_test.go

@@ -1,119 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package task
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-type stubAPIClient struct {
-	err error
-
-	method string
-	path   string
-	body   interface{}
-	calls  int
-}
-
-func (s *stubAPIClient) CallAPI(_ context.Context, method, path string, body interface{}) (json.RawMessage, error) {
-	s.method = method
-	s.path = path
-	s.body = body
-	s.calls++
-	if s.err != nil {
-		return nil, s.err
-	}
-	return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
-}
-
-func TestTaskSubscriptionPreConsumeCallsSubscribeAPI(t *testing.T) {
-	rt := &stubAPIClient{}
-	cleanup, err := taskSubscriptionPreConsume(context.Background(), rt, nil)
-	if err != nil {
-		t.Fatalf("taskSubscriptionPreConsume error = %v", err)
-	}
-	if cleanup != nil {
-		t.Fatal("cleanup = non-nil, want nil because task subscription has no unsubscribe API")
-	}
-	if rt.calls != 1 {
-		t.Fatalf("calls = %d, want 1", rt.calls)
-	}
-	if rt.method != "POST" {
-		t.Errorf("method = %q, want POST", rt.method)
-	}
-	if rt.path != taskSubscriptionPath {
-		t.Errorf("path = %q, want %q", rt.path, taskSubscriptionPath)
-	}
-	if rt.body != nil {
-		t.Errorf("body = %#v, want nil", rt.body)
-	}
-}
-
-func TestTaskSubscriptionPreConsumeRequiresRuntime(t *testing.T) {
-	_, err := taskSubscriptionPreConsume(context.Background(), nil, nil)
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryInternal {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryInternal)
-	}
-	if p.Subtype != errs.SubtypeUnknown {
-		t.Errorf("subtype = %s, want %s", p.Subtype, errs.SubtypeUnknown)
-	}
-}
-
-func TestTaskSubscriptionPreConsumePassesThroughAPIError(t *testing.T) {
-	wantErr := errs.NewValidationError(errs.SubtypeFailedPrecondition, "subscription already exists")
-	rt := &stubAPIClient{err: wantErr}
-
-	_, err := taskSubscriptionPreConsume(context.Background(), rt, nil)
-	if err != wantErr {
-		t.Fatalf("err identity changed: got %T %v, want original %T %v", err, err, wantErr, wantErr)
-	}
-	if !errors.Is(err, wantErr) {
-		t.Fatalf("err = %v, want %v", err, wantErr)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryValidation {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryValidation)
-	}
-	if p.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("subtype = %s, want %s", p.Subtype, errs.SubtypeFailedPrecondition)
-	}
-}
-
-func TestTaskSubscriptionPreConsumeWrapsUntypedAPIError(t *testing.T) {
-	cause := errors.New("connection reset")
-	rt := &stubAPIClient{err: cause}
-
-	_, err := taskSubscriptionPreConsume(context.Background(), rt, nil)
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	if !errors.Is(err, cause) {
-		t.Fatalf("err = %v, want cause %v", err, cause)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T: %v", err, err)
-	}
-	if p.Category != errs.CategoryNetwork {
-		t.Errorf("category = %s, want %s", p.Category, errs.CategoryNetwork)
-	}
-	if p.Subtype != errs.SubtypeNetworkTransport {
-		t.Errorf("subtype = %s, want %s", p.Subtype, errs.SubtypeNetworkTransport)
-	}
-}

events/task/register.go

@@ -1,33 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package task registers Task-domain EventKeys.
-package task
-
-import (
-	"reflect"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-const eventTypeTaskUpdateUserAccessV2 = "task.task.update_user_access_v2"
-
-// Keys returns all Task-domain EventKey definitions.
-func Keys() []event.KeyDefinition {
-	return []event.KeyDefinition{
-		{
-			Key:         eventTypeTaskUpdateUserAccessV2,
-			DisplayName: "Task updated",
-			Description: "Triggered when tasks visible to the current user or app are created, deleted, or updated",
-			EventType:   eventTypeTaskUpdateUserAccessV2,
-			Schema: event.SchemaDef{
-				Native: &event.SchemaSpec{Type: reflect.TypeOf(TaskUpdateUserAccessV2Data{})},
-			},
-			PreConsume:            taskSubscriptionPreConsume,
-			Scopes:                []string{"task:task:read"},
-			AuthTypes:             []string{"user", "bot"},
-			RequiredConsoleEvents: []string{eventTypeTaskUpdateUserAccessV2},
-			SingleConsumer:        true,
-		},
-	}
-}

events/task/register_test.go

@@ -1,95 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package task
-
-import (
-	"encoding/json"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/internal/event"
-	"github.com/larksuite/cli/internal/event/schemas"
-)
-
-func TestKeysTaskUpdateUserAccessMetadata(t *testing.T) {
-	keys := Keys()
-	if len(keys) != 1 {
-		t.Fatalf("len(Keys()) = %d, want 1", len(keys))
-	}
-
-	def := keys[0]
-	if def.Key != eventTypeTaskUpdateUserAccessV2 {
-		t.Errorf("Key = %q, want %q", def.Key, eventTypeTaskUpdateUserAccessV2)
-	}
-	if def.EventType != eventTypeTaskUpdateUserAccessV2 {
-		t.Errorf("EventType = %q, want %q", def.EventType, eventTypeTaskUpdateUserAccessV2)
-	}
-	if def.Schema.Native == nil {
-		t.Fatal("Schema.Native is nil")
-	}
-	if def.Schema.Native.Type != reflect.TypeOf(TaskUpdateUserAccessV2Data{}) {
-		t.Errorf("native type = %v, want TaskUpdateUserAccessV2Data", def.Schema.Native.Type)
-	}
-	if def.Process != nil {
-		t.Fatal("Native Task EventKey must not set Process")
-	}
-	if def.PreConsume == nil {
-		t.Fatal("PreConsume is nil")
-	}
-	if !def.SingleConsumer {
-		t.Fatal("SingleConsumer = false, want true")
-	}
-	if !reflect.DeepEqual(def.Scopes, []string{"task:task:read"}) {
-		t.Errorf("Scopes = %#v", def.Scopes)
-	}
-	if !reflect.DeepEqual(def.AuthTypes, []string{"user", "bot"}) {
-		t.Errorf("AuthTypes = %#v", def.AuthTypes)
-	}
-	if !reflect.DeepEqual(def.RequiredConsoleEvents, []string{eventTypeTaskUpdateUserAccessV2}) {
-		t.Errorf("RequiredConsoleEvents = %#v", def.RequiredConsoleEvents)
-	}
-}
-
-func TestTaskUpdateUserAccessSchemaAnnotations(t *testing.T) {
-	raw := schemas.WrapV2Envelope(schemas.FromType(reflect.TypeOf(TaskUpdateUserAccessV2Data{})))
-	var schema map[string]interface{}
-	if err := json.Unmarshal(raw, &schema); err != nil {
-		t.Fatalf("unmarshal schema: %v", err)
-	}
-
-	eventProps := schema["properties"].(map[string]interface{})["event"].(map[string]interface{})["properties"].(map[string]interface{})
-	taskGUID := eventProps["task_guid"].(map[string]interface{})
-	if got := taskGUID["format"]; got != "task_guid" {
-		t.Errorf("task_guid format = %v, want task_guid", got)
-	}
-
-	eventTypes := eventProps["event_types"].(map[string]interface{})
-	items := eventTypes["items"].(map[string]interface{})
-	rawEnum, ok := items["enum"].([]interface{})
-	if !ok {
-		t.Fatalf("event_types item enum missing: %#v", items["enum"])
-	}
-	got := make(map[string]bool, len(rawEnum))
-	for _, v := range rawEnum {
-		got[v.(string)] = true
-	}
-	for _, want := range taskUpdateUserAccessCommitTypes {
-		if !got[want] {
-			t.Errorf("event_types enum missing %q; enum=%v", want, rawEnum)
-		}
-	}
-}
-
-func TestTaskUpdateUserAccessRegistersCleanly(t *testing.T) {
-	const key = eventTypeTaskUpdateUserAccessV2
-	event.UnregisterKeyForTest(key)
-	t.Cleanup(func() { event.UnregisterKeyForTest(key) })
-
-	for _, def := range Keys() {
-		event.RegisterKey(def)
-	}
-	if _, ok := event.Lookup(key); !ok {
-		t.Fatalf("event.Lookup(%q) not registered", key)
-	}
-}

events/vc/participant_meeting_joined.go

@@ -1,62 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-// VCParticipantMeetingJoinedOutput is the flattened shape for vc.meeting.participant_meeting_joined_v1.
-type VCParticipantMeetingJoinedOutput struct {
-	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_joined_v1"`
-	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
-	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
-	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID" kind:"meeting_id"`
-	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
-	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
-	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
-	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
-}
-
-func processVCParticipantMeetingJoined(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
-	var envelope struct {
-		Header struct {
-			EventID    string `json:"event_id"`
-			EventType  string `json:"event_type"`
-			CreateTime string `json:"create_time"`
-		} `json:"header"`
-		Event struct {
-			Meeting struct {
-				ID              string `json:"id"`
-				Topic           string `json:"topic"`
-				MeetingNo       string `json:"meeting_no"`
-				StartTime       string `json:"start_time"`
-				EndTime         string `json:"end_time"`
-				CalendarEventID string `json:"calendar_event_id"`
-			} `json:"meeting"`
-		} `json:"event"`
-	}
-	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
-		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
-	}
-
-	meeting := envelope.Event.Meeting
-	out := &VCParticipantMeetingJoinedOutput{
-		Type:            envelope.Header.EventType,
-		EventID:         envelope.Header.EventID,
-		Timestamp:       envelope.Header.CreateTime,
-		MeetingID:       meeting.ID,
-		Topic:           meeting.Topic,
-		MeetingNo:       meeting.MeetingNo,
-		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
-		CalendarEventID: meeting.CalendarEventID,
-	}
-	if out.Type == "" {
-		out.Type = raw.EventType
-	}
-	return json.Marshal(out)
-}

events/vc/participant_meeting_lifecycle_test.go

@@ -1,281 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"context"
-	"encoding/json"
-	"reflect"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-func TestVCKeys_ProcessedMeetingLifecycleRegistered(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	for _, tc := range []struct {
-		eventType  string
-		schemaType reflect.Type
-	}{
-		{eventTypeMeetingStarted, reflect.TypeOf(VCParticipantMeetingStartedOutput{})},
-		{eventTypeMeetingJoined, reflect.TypeOf(VCParticipantMeetingJoinedOutput{})},
-	} {
-		t.Run(tc.eventType, func(t *testing.T) {
-			def, ok := event.Lookup(tc.eventType)
-			if !ok {
-				t.Fatalf("%s should be registered via Keys()", tc.eventType)
-			}
-			if def.Schema.Custom == nil {
-				t.Error("Processed key must set Schema.Custom")
-			}
-			if def.Schema.Native != nil {
-				t.Error("Processed key must not set Schema.Native")
-			}
-			if def.Process == nil {
-				t.Error("Process must not be nil for processed key")
-			}
-			if def.PreConsume == nil {
-				t.Error("PreConsume must not be nil for processed key")
-			}
-			if len(def.Scopes) != 1 || def.Scopes[0] != "vc:meeting.meetingevent:read" {
-				t.Errorf("Scopes = %v", def.Scopes)
-			}
-			if len(def.AuthTypes) != 1 || def.AuthTypes[0] != "user" {
-				t.Errorf("AuthTypes = %v", def.AuthTypes)
-			}
-			if len(def.RequiredConsoleEvents) != 1 || def.RequiredConsoleEvents[0] != tc.eventType {
-				t.Errorf("RequiredConsoleEvents = %v", def.RequiredConsoleEvents)
-			}
-			if def.Schema.Custom.Type != tc.schemaType {
-				t.Errorf("Custom schema Type = %v, want %v", def.Schema.Custom.Type, tc.schemaType)
-			}
-		})
-	}
-}
-
-func TestProcessVCParticipantMeetingLifecycle(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	for _, tc := range []struct {
-		name      string
-		eventType string
-		process   event.ProcessFunc
-	}{
-		{
-			name:      "started",
-			eventType: eventTypeMeetingStarted,
-			process:   processVCParticipantMeetingStarted,
-		},
-		{
-			name:      "joined",
-			eventType: eventTypeMeetingJoined,
-			process:   processVCParticipantMeetingJoined,
-		},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			payload := `{
-				"schema": "2.0",
-				"header": {
-					"event_id": "ev_vc_lifecycle_001",
-					"event_type": "` + tc.eventType + `",
-					"create_time": "1608725989000",
-					"app_id": "cli_test"
-				},
-				"event": {
-					"meeting": {
-						"id": "6911188411934433028",
-						"topic": "my meeting",
-						"meeting_no": "235812466",
-						"start_time": "1608883322",
-						"end_time": "1608883899",
-						"calendar_event_id": "efa67a98-06a8-4df5-8559-746c8f4477ef_0"
-					}
-				}
-			}`
-			out := runMeetingLifecycleMap(t, tc.eventType, tc.process, payload)
-
-			if out["type"] != tc.eventType {
-				t.Errorf("type = %q", out["type"])
-			}
-			if out["event_id"] != "ev_vc_lifecycle_001" {
-				t.Errorf("event_id = %q", out["event_id"])
-			}
-			if out["timestamp"] != "1608725989000" {
-				t.Errorf("timestamp = %q", out["timestamp"])
-			}
-			if out["meeting_id"] != "6911188411934433028" {
-				t.Errorf("meeting_id = %q", out["meeting_id"])
-			}
-			if out["topic"] != "my meeting" || out["meeting_no"] != "235812466" {
-				t.Errorf("topic/meeting_no = %q/%q", out["topic"], out["meeting_no"])
-			}
-			if out["calendar_event_id"] != "efa67a98-06a8-4df5-8559-746c8f4477ef_0" {
-				t.Errorf("calendar_event_id = %q", out["calendar_event_id"])
-			}
-			if want := time.Unix(1608883322, 0).Local().Format(time.RFC3339); out["start_time"] != want {
-				t.Errorf("start_time = %q, want %q", out["start_time"], want)
-			}
-			if _, hasEndTime := out["end_time"]; hasEndTime {
-				t.Error("end_time should not be present in started/joined output")
-			}
-		})
-	}
-}
-
-func TestProcessVCParticipantMeetingLifecycle_InvalidMeetingTimes(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	for _, tc := range []struct {
-		name      string
-		eventType string
-		process   event.ProcessFunc
-	}{
-		{"started", eventTypeMeetingStarted, processVCParticipantMeetingStarted},
-		{"joined", eventTypeMeetingJoined, processVCParticipantMeetingJoined},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			payload := `{
-				"schema": "2.0",
-				"header": {
-					"event_id": "ev_vc_lifecycle_002",
-					"event_type": "` + tc.eventType + `",
-					"create_time": "1608725989001"
-				},
-				"event": {
-					"meeting": {
-						"id": "meeting_invalid_time",
-						"start_time": "bad",
-						"end_time": ""
-					}
-				}
-			}`
-			out := runMeetingLifecycleRaw(t, tc.eventType, tc.process, payload)
-			switch tc.eventType {
-			case eventTypeMeetingStarted:
-				var started VCParticipantMeetingStartedOutput
-				if err := json.Unmarshal(out, &started); err != nil {
-					t.Fatalf("Process output is not valid started JSON: %v\nraw=%s", err, string(out))
-				}
-				if started.StartTime != "" {
-					t.Errorf("StartTime = %q, want empty string", started.StartTime)
-				}
-			case eventTypeMeetingJoined:
-				var joined VCParticipantMeetingJoinedOutput
-				if err := json.Unmarshal(out, &joined); err != nil {
-					t.Fatalf("Process output is not valid joined JSON: %v\nraw=%s", err, string(out))
-				}
-				if joined.StartTime != "" {
-					t.Errorf("StartTime = %q, want empty string", joined.StartTime)
-				}
-			}
-		})
-	}
-}
-
-func TestProcessVCParticipantMeetingLifecycle_MalformedPayload(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	for _, tc := range []struct {
-		name      string
-		eventType string
-		process   event.ProcessFunc
-	}{
-		{"started", eventTypeMeetingStarted, processVCParticipantMeetingStarted},
-		{"joined", eventTypeMeetingJoined, processVCParticipantMeetingJoined},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			raw := &event.RawEvent{
-				EventType: tc.eventType,
-				Payload:   json.RawMessage(`not json`),
-				Timestamp: time.Now(),
-			}
-			got, err := tc.process(context.Background(), nil, raw, nil)
-			if err != nil {
-				t.Fatalf("Process should swallow parse errors, got %v", err)
-			}
-			if string(got) != "not json" {
-				t.Errorf("malformed fallback output = %q, want original bytes", string(got))
-			}
-		})
-	}
-}
-
-func TestVCParticipantMeetingLifecycle_PreConsumeSubscriptionLifecycle(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-
-	for _, eventType := range []string{eventTypeMeetingStarted, eventTypeMeetingJoined} {
-		t.Run(eventType, func(t *testing.T) {
-			def, ok := event.Lookup(eventType)
-			if !ok {
-				t.Fatalf("%s should be registered via Keys()", eventType)
-			}
-
-			type call struct {
-				method string
-				path   string
-				body   any
-			}
-			var calls []call
-			rt := &stubAPIClient{
-				callFn: func(_ context.Context, method, path string, body any) (json.RawMessage, error) {
-					calls = append(calls, call{method: method, path: path, body: body})
-					return json.RawMessage(`{"code":0,"msg":"success","data":{}}`), nil
-				},
-			}
-
-			cleanup, err := def.PreConsume(context.Background(), rt, nil)
-			if err != nil {
-				t.Fatalf("PreConsume error: %v", err)
-			}
-			if cleanup == nil {
-				t.Fatal("cleanup must not be nil")
-			}
-			if len(calls) != 1 {
-				t.Fatalf("calls after subscribe = %d, want 1", len(calls))
-			}
-			if calls[0].method != "POST" || calls[0].path != pathMeetingSubscribe {
-				t.Fatalf("subscribe call = %+v", calls[0])
-			}
-			assertSubscriptionRequest(t, calls[0].body, eventType)
-
-			cleanup()
-			if len(calls) != 2 {
-				t.Fatalf("calls after cleanup = %d, want 2", len(calls))
-			}
-			if calls[1].method != "POST" || calls[1].path != pathMeetingUnsubscribe {
-				t.Fatalf("unsubscribe call = %+v", calls[1])
-			}
-			assertSubscriptionRequest(t, calls[1].body, eventType)
-		})
-	}
-}
-
-func runMeetingLifecycleMap(t *testing.T, eventType string, process event.ProcessFunc, payload string) map[string]string {
-	t.Helper()
-	got := runMeetingLifecycleRaw(t, eventType, process, payload)
-	if got == nil {
-		t.Fatal("Process output is nil")
-	}
-	var out map[string]string
-	if err := json.Unmarshal(got, &out); err != nil {
-		t.Fatalf("Process output is not valid flat JSON object: %v\nraw=%s", err, string(got))
-	}
-	return out
-}
-
-func runMeetingLifecycleRaw(t *testing.T, eventType string, process event.ProcessFunc, payload string) json.RawMessage {
-	t.Helper()
-	raw := &event.RawEvent{
-		EventType: eventType,
-		Payload:   json.RawMessage(payload),
-		Timestamp: time.Now(),
-	}
-	got, err := process(context.Background(), nil, raw, nil)
-	if err != nil {
-		t.Fatalf("Process error: %v", err)
-	}
-	return got
-}

events/vc/participant_meeting_started.go

@@ -1,61 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/larksuite/cli/internal/event"
-)
-
-// VCParticipantMeetingStartedOutput is the flattened shape for vc.meeting.participant_meeting_started_v1.
-type VCParticipantMeetingStartedOutput struct {
-	Type            string `json:"type"                      desc:"Event type; always vc.meeting.participant_meeting_started_v1"`
-	EventID         string `json:"event_id,omitempty"        desc:"Globally unique event ID; safe for deduplication"`
-	Timestamp       string `json:"timestamp,omitempty"       desc:"Event delivery time (ms timestamp string); taken from header.create_time when present" kind:"timestamp_ms"`
-	MeetingID       string `json:"meeting_id,omitempty"      desc:"Meeting ID" kind:"meeting_id"`
-	Topic           string `json:"topic,omitempty"           desc:"Meeting topic"`
-	MeetingNo       string `json:"meeting_no,omitempty"      desc:"Meeting number"`
-	StartTime       string `json:"start_time,omitempty"      desc:"Meeting start time in RFC3339, converted to the local timezone"`
-	CalendarEventID string `json:"calendar_event_id,omitempty" desc:"Calendar event ID associated with the meeting"`
-}
-
-func processVCParticipantMeetingStarted(_ context.Context, _ event.APIClient, raw *event.RawEvent, _ map[string]string) (json.RawMessage, error) {
-	var envelope struct {
-		Header struct {
-			EventID    string `json:"event_id"`
-			EventType  string `json:"event_type"`
-			CreateTime string `json:"create_time"`
-		} `json:"header"`
-		Event struct {
-			Meeting struct {
-				ID              string `json:"id"`
-				Topic           string `json:"topic"`
-				MeetingNo       string `json:"meeting_no"`
-				StartTime       string `json:"start_time"`
-				CalendarEventID string `json:"calendar_event_id"`
-			} `json:"meeting"`
-		} `json:"event"`
-	}
-	if err := json.Unmarshal(raw.Payload, &envelope); err != nil {
-		return raw.Payload, nil //nolint:nilerr // passthrough on malformed payload so consumers still see the event
-	}
-
-	meeting := envelope.Event.Meeting
-	out := &VCParticipantMeetingStartedOutput{
-		Type:            envelope.Header.EventType,
-		EventID:         envelope.Header.EventID,
-		Timestamp:       envelope.Header.CreateTime,
-		MeetingID:       meeting.ID,
-		Topic:           meeting.Topic,
-		MeetingNo:       meeting.MeetingNo,
-		StartTime:       unixSecondsToLocalRFC3339(meeting.StartTime),
-		CalendarEventID: meeting.CalendarEventID,
-	}
-	if out.Type == "" {
-		out.Type = raw.EventType
-	}
-	return json.Marshal(out)
-}

events/vc/register.go

@@ -11,8 +11,6 @@ import (
 )
 
 const (
-	eventTypeMeetingStarted               = "vc.meeting.participant_meeting_started_v1"
-	eventTypeMeetingJoined                = "vc.meeting.participant_meeting_joined_v1"
 	eventTypeMeetingEnded                 = "vc.meeting.participant_meeting_ended_v1"
 	eventTypeNoteGenerated                = "vc.note.generated_v1"
 	eventTypeRecordingStarted             = "vc.recording.recording_started_v1"
@@ -32,38 +30,6 @@ const (
 // Keys returns all VC-domain EventKey definitions.
 func Keys() []event.KeyDefinition {
 	return []event.KeyDefinition{
-		{
-			Key:         eventTypeMeetingStarted,
-			DisplayName: "Participant meeting started",
-			Description: "Triggered when a meeting the current user participates in has started",
-			EventType:   eventTypeMeetingStarted,
-			Schema: event.SchemaDef{
-				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingStartedOutput{})},
-			},
-			Process:    processVCParticipantMeetingStarted,
-			PreConsume: subscriptionPreConsume(eventTypeMeetingStarted, pathMeetingSubscribe, pathMeetingUnsubscribe),
-			Scopes:     []string{"vc:meeting.meetingevent:read"},
-			AuthTypes: []string{
-				"user",
-			},
-			RequiredConsoleEvents: []string{eventTypeMeetingStarted},
-		},
-		{
-			Key:         eventTypeMeetingJoined,
-			DisplayName: "Participant meeting joined",
-			Description: "Triggered when the current user joins a meeting",
-			EventType:   eventTypeMeetingJoined,
-			Schema: event.SchemaDef{
-				Custom: &event.SchemaSpec{Type: reflect.TypeOf(VCParticipantMeetingJoinedOutput{})},
-			},
-			Process:    processVCParticipantMeetingJoined,
-			PreConsume: subscriptionPreConsume(eventTypeMeetingJoined, pathMeetingSubscribe, pathMeetingUnsubscribe),
-			Scopes:     []string{"vc:meeting.meetingevent:read"},
-			AuthTypes: []string{
-				"user",
-			},
-			RequiredConsoleEvents: []string{eventTypeMeetingJoined},
-		},
 		{
 			Key:         eventTypeMeetingEnded,
 			DisplayName: "Participant meeting ended",

go.mod

@@ -7,6 +7,8 @@ require (
 	github.com/bmatcuk/doublestar/v4 v4.10.0
 	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/facebookincubator/flog v0.0.0-20190930132826-d2511d0ce33c
+	github.com/facebookincubator/sks v0.0.0-20251112220143-6823f23937b4
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
@@ -27,7 +29,10 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 )
 
+require github.com/ebitengine/purego v0.10.1
+
 require (
+	github.com/StackExchange/wmi v1.2.1 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
@@ -42,12 +47,23 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
+	github.com/go-ole/go-ole v1.2.5 // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/btree v1.0.1 // indirect
+	github.com/google/certificate-transparency-go v1.1.2 // indirect
+	github.com/google/certtostore v1.0.3-0.20230404221207-8d01647071cc // indirect
+	github.com/google/deck v0.0.0-20230104221208-105ad94aa8ae // indirect
+	github.com/google/go-attestation v0.5.1 // indirect
+	github.com/google/go-tpm v0.9.0 // indirect
+	github.com/google/go-tspi v0.3.0 // indirect
 	github.com/gopherjs/gopherjs v1.17.2 // indirect
 	github.com/gorilla/websocket v1.5.0 // indirect
+	github.com/hashicorp/errwrap v1.0.0 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/itchyny/timefmt-go v0.1.6 // indirect
+	github.com/jgoguen/go-utils v0.0.0-20200211015258-b42ad41486fd // indirect
 	github.com/jtolds/gls v4.20.0+incompatible // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -57,10 +73,12 @@ require (
 	github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 // indirect
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
+	github.com/peterbourgon/diskv v2.0.1+incompatible // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/smarty/assertions v1.15.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
+	golang.org/x/crypto v0.31.0 // indirect
 )

internal/affordance/affordance.go

@@ -1,96 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package affordance is the lazily-loaded store of usage guidance for
-// service-API methods. The source of truth is one markdown file per service in
-// the top-level affordance/ tree (see mdparse.go), injected via SetSource so
-// domain owners maintain it next to skills/ and shortcuts/. A service is read
-// and parsed at most once, on first access, so normal command execution never
-// touches it.
-package affordance
-
-import (
-	"encoding/json"
-	"io/fs"
-	"strings"
-	"sync"
-
-	"github.com/larksuite/cli/internal/apicatalog"
-	"github.com/larksuite/cli/internal/registry"
-)
-
-var (
-	mu        sync.Mutex
-	byService = map[string]map[string]json.RawMessage{}
-	tried     = map[string]bool{}
-	mdSource  fs.FS // top-level affordance/*.md tree; nil in the minimal preview build
-)
-
-// SetSource installs the markdown guidance tree (the top-level affordance/
-// directory) as the source. Called once at startup before any lookup; clears
-// the parse cache so re-sourcing (e.g. in tests) takes effect.
-func SetSource(fsys fs.FS) {
-	mu.Lock()
-	defer mu.Unlock()
-	mdSource = fsys
-	byService = map[string]map[string]json.RawMessage{}
-	tried = map[string]bool{}
-}
-
-// For returns the raw affordance overlay for one method, loading the owning
-// service on first access. ok is false when there is no entry (absent source,
-// parse failure, or unknown method all collapse to "no guidance").
-func For(service, methodID string) (json.RawMessage, bool) {
-	mu.Lock()
-	defer mu.Unlock()
-	if !tried[service] {
-		tried[service] = true
-		byService[service] = loadService(service)
-	}
-	raw, ok := byService[service][methodID]
-	return raw, ok && len(raw) > 0
-}
-
-// loadService parses a service's markdown guidance into per-method overlays,
-// marshalling each to JSON so downstream callers keep the same wire shape.
-func loadService(service string) map[string]json.RawMessage {
-	if mdSource == nil {
-		return nil
-	}
-	src, err := fs.ReadFile(mdSource, service+".md")
-	if err != nil {
-		return nil
-	}
-	m := map[string]json.RawMessage{}
-	for id, a := range parseDomainMD(src, commandFormResolver(service)) {
-		if b, err := json.Marshal(a); err == nil {
-			m[id] = b
-		}
-	}
-	return m
-}
-
-// commandFormResolver maps a method's command-form heading ("user_mailbox.messages
-// list") to its method id ("user_mailbox.message.list") via the registry's
-// authoritative resource↔id table. Resource names are irregularly pluralised
-// (message/messages, user_mailbox/user_mailboxes), so this cannot be guessed; the
-// space→dot fallback covers domains where the two already coincide.
-func commandFormResolver(service string) func(string) string {
-	byForm := map[string]string{}
-	for _, svc := range registry.EmbeddedServicesTyped() {
-		if svc.Name != service {
-			continue
-		}
-		for _, ref := range apicatalog.ServiceMethods(svc, nil) {
-			byForm[strings.Join(ref.CommandPath()[1:], " ")] = ref.Method.ID
-		}
-		break
-	}
-	return func(h string) string {
-		h = strings.TrimSpace(h)
-		if id, ok := byForm[h]; ok {
-			return id
-		}
-		return strings.ReplaceAll(h, " ", ".")
-	}
-}

internal/affordance/affordance_test.go

@@ -1,86 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package affordance
-
-import (
-	"encoding/json"
-	"testing"
-	"testing/fstest"
-)
-
-// fixtureMD is a minimal affordance source: two methods, each with a lead
-// paragraph (use_when) and a fenced example.
-const fixtureMD = "# approval\n" +
-	"> skill: lark-approval\n\n" +
-	"## instances cc\n" +
-	"把一个审批实例抄送给指定用户。\n\n" +
-	"### Examples\n\n" +
-	"**抄送给用户**\n" +
-	"```bash\n" +
-	"lark-cli approval instances cc --data '{\"instance_code\":\"x\"}'\n" +
-	"```\n\n" +
-	"## instances get\n" +
-	"查询某审批实例详情。\n\n" +
-	"### Examples\n\n" +
-	"**按 code 查询**\n" +
-	"```bash\n" +
-	"lark-cli approval instances get --instance-code \"x\"\n" +
-	"```\n"
-
-func TestFor(t *testing.T) {
-	prev := mdSource
-	t.Cleanup(func() { SetSource(prev) }) // SetSource mutates package state; restore for test isolation
-	SetSource(fstest.MapFS{"approval.md": &fstest.MapFile{Data: []byte(fixtureMD)}})
-
-	// A seeded method in a seeded service resolves to its overlay.
-	raw, ok := For("approval", "instances.cc")
-	if !ok {
-		t.Fatal(`For("approval","instances.cc") ok=false, want an overlay`)
-	}
-	var a struct {
-		UseWhen  []string `json:"use_when"`
-		Examples []struct {
-			Command string `json:"command"`
-		} `json:"examples"`
-	}
-	if err := json.Unmarshal(raw, &a); err != nil {
-		t.Fatalf("overlay is not valid affordance JSON: %v", err)
-	}
-	if len(a.UseWhen) == 0 || len(a.Examples) == 0 || a.Examples[0].Command == "" {
-		t.Errorf("overlay missing use_when/examples: %s", raw)
-	}
-
-	// Misses: unknown method in a known service, and an unknown service, both
-	// resolve to ok=false (no panic, no error) so callers treat them as "no
-	// guidance".
-	if _, ok := For("approval", "instances.no_such_method"); ok {
-		t.Error("unknown method should be ok=false")
-	}
-	if _, ok := For("no_such_service", "x.y"); ok {
-		t.Error("unknown service should be ok=false")
-	}
-
-	// A second lookup of the same service is served from cache (parsed at most
-	// once) and stays consistent.
-	if _, ok := For("approval", "instances.get"); !ok {
-		t.Error("second lookup in a cached service should still resolve")
-	}
-}
-
-// Non-bullet paragraph lines under any section are preserved as items, not
-// dropped (regression: they previously only updated pending, lost without a fence).
-func TestParseDomainMD_ParagraphNotDropped(t *testing.T) {
-	md := "# d\n\n## foo bar\nwhat it does.\n\n### Tips\n- a bullet\nplain paragraph note.\n\n### See also\nrun [[other cmd]] first.\n"
-	got := parseDomainMD([]byte(md), nil) // nil resolver -> space->dot, "foo bar" -> "foo.bar"
-	a, ok := got["foo.bar"]
-	if !ok {
-		t.Fatal("method not parsed")
-	}
-	if len(a.Tips) != 2 || a.Tips[1] != "plain paragraph note." {
-		t.Errorf("Tips paragraph dropped: %v", a.Tips)
-	}
-	if len(a.Extensions) != 1 || len(a.Extensions[0].Items) != 1 || a.Extensions[0].Items[0] != "run `other cmd` first." {
-		t.Errorf("custom-section paragraph not flowed through: %+v", a.Extensions)
-	}
-}

internal/affordance/mdparse.go

@@ -1,180 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package affordance
-
-import (
-	"regexp"
-	"strings"
-
-	"github.com/larksuite/cli/internal/meta"
-)
-
-// The affordance source is a narrow, fixed markdown subset (see src/*.md):
-//
-//	# domain            optional `> skill: <name>` applied to every method
-//	## command          e.g. `instances get`
-//	<lead paragraph>    -> use_when (when this command is right)
-//	### Avoid when      -> avoid_when (links become prefer/alternative edges)
-//	### Prerequisites   -> prerequisites   (a "…来自 [[x]]" link is a sequence edge)
-//	### Tips            -> tips
-//	### Examples        -> examples: **description** + a ```fenced``` command
-//	### <other>         -> extensions[] (custom section, flows through verbatim)
-//	[[cmd]]             -> a command reference, rendered as `cmd`
-//
-// Parsing is lazy and cached (see For), so the constrained grammar is read at
-// most once per domain.
-
-var mdLink = regexp.MustCompile(`\[\[(.+?)\]\]`)
-
-// standardSection maps a section heading to its typed Affordance field; any
-// other heading becomes an extension.
-var standardSection = map[string]string{
-	"Avoid when":    "avoid_when",
-	"Prerequisites": "prerequisites",
-	"Tips":          "tips",
-	"Examples":      "examples",
-}
-
-func linkToBacktick(s string) string { return mdLink.ReplaceAllString(s, "`$1`") }
-
-// headingToKey maps a command heading ("instances get") to its affordance key
-// ("instances.get"). The space→dot rule holds where the command form matches
-// the method id; domains whose resource names differ (e.g. plural "messages"
-// vs id segment "message") need the registry's authoritative resource↔id table.
-func headingToKey(h string) string {
-	return strings.ReplaceAll(strings.TrimSpace(h), " ", ".")
-}
-
-type mdSection struct {
-	label string
-	items []string
-	cases []meta.AffordanceCase
-}
-
-// parseDomainMD parses one domain's markdown into per-method Affordance values,
-// keyed by method id. resolve maps a command-form heading ("user_mailbox.messages
-// list") to its method id ("user_mailbox.message.list"); nil falls back to the
-// space→dot rule (valid only where the command form already equals the id).
-func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affordance {
-	if resolve == nil {
-		resolve = headingToKey
-	}
-	out := map[string]meta.Affordance{}
-
-	var skill, curKey string
-	var useWhen, para []string // lead paragraphs -> use_when entries (blank line separates)
-	var secs []*mdSection
-	var sec *mdSection
-	var pending string
-	var fence []string
-	inFence := false
-
-	assemble := func() {
-		if curKey == "" {
-			return
-		}
-		if len(para) > 0 {
-			useWhen = append(useWhen, strings.TrimSpace(strings.Join(para, " ")))
-			para = nil
-		}
-		var a meta.Affordance
-		if len(useWhen) > 0 {
-			a.UseWhen = useWhen
-		}
-		for _, s := range secs {
-			switch standardSection[s.label] {
-			case "avoid_when":
-				a.AvoidWhen = s.items
-			case "prerequisites":
-				a.Prerequisites = s.items
-			case "tips":
-				a.Tips = s.items
-			case "examples":
-				a.Examples = s.cases
-			default:
-				a.Extensions = append(a.Extensions, meta.AffordanceSection{Label: s.label, Items: s.items})
-			}
-		}
-		if skill != "" {
-			a.Skills = []string{skill}
-		}
-		out[curKey] = a
-	}
-
-	reset := func() { useWhen, para, secs, sec, pending, fence, inFence = nil, nil, nil, nil, "", nil, false }
-
-	// flushPending appends a non-bullet paragraph line that was not consumed as
-	// an example description (i.e. no fence followed) to the current section's
-	// items, so prose under any section is preserved rather than dropped.
-	flushPending := func() {
-		if sec != nil && pending != "" {
-			sec.items = append(sec.items, linkToBacktick(pending))
-			pending = ""
-		}
-	}
-
-	for _, raw := range strings.Split(string(src), "\n") {
-		line := strings.TrimRight(raw, "\r")
-		t := strings.TrimSpace(line)
-		switch {
-		case strings.HasPrefix(line, "## "):
-			flushPending()
-			assemble()
-			curKey = resolve(line[3:])
-			reset()
-			continue
-		case strings.HasPrefix(line, "# "):
-			continue
-		case strings.HasPrefix(t, "> skill:"):
-			skill = strings.TrimSpace(t[len("> skill:"):])
-			continue
-		case strings.HasPrefix(line, "### "):
-			flushPending()
-			sec = &mdSection{label: strings.TrimSpace(line[4:])}
-			secs = append(secs, sec)
-			pending, fence, inFence = "", nil, false
-			continue
-		}
-		if curKey == "" {
-			continue
-		}
-		if sec == nil { // lead paragraphs before any section -> use_when (blank line separates entries)
-			if t == "" {
-				if len(para) > 0 {
-					useWhen = append(useWhen, strings.Join(para, " "))
-					para = nil
-				}
-			} else {
-				para = append(para, t)
-			}
-			continue
-		}
-		// inside a section: a fenced block is an example command; otherwise the
-		// shape follows the writing (bullet item vs **description** before a fence).
-		if strings.HasPrefix(t, "```") {
-			if !inFence {
-				inFence, fence = true, nil
-			} else {
-				inFence = false
-				sec.cases = append(sec.cases, meta.AffordanceCase{Description: pending, Command: strings.Join(fence, "\n")})
-				pending = ""
-			}
-			continue
-		}
-		if inFence {
-			fence = append(fence, line)
-			continue
-		}
-		if strings.HasPrefix(t, "-") {
-			flushPending()
-			sec.items = append(sec.items, linkToBacktick(strings.TrimSpace(t[1:])))
-		} else if t != "" {
-			flushPending()
-			pending = strings.Trim(t, "* ")
-		}
-	}
-	flushPending()
-	assemble()
-	return out
-}

internal/auth/app_registration.go

@@ -31,6 +31,11 @@ type AppRegistrationResult struct {
 	ClientID     string
 	ClientSecret string
 	UserInfo     *AppRegUserInfo
+	// AuthMethods is the authoritative auth method(s) the app must use, as
+	// decided by the user/admin at confirmation (20260409 `auth_method` field).
+	// It may differ from what the client requested — e.g. selecting an existing
+	// client_secret app. Empty on older servers.
+	AuthMethods []string
 }
 
 // AppRegUserInfo contains user info returned from app registration.
@@ -39,8 +44,81 @@ type AppRegUserInfo struct {
 	TenantBrand string // "feishu" or "lark"
 }
 
-// RequestAppRegistration initiates the app registration device flow.
-func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOut io.Writer) (*AppRegistrationResponse, error) {
+// AppRegistrationInit is the response from the app registration init endpoint.
+type AppRegistrationInit struct {
+	Nonce                string
+	SupportedAuthMethods []string // e.g. ["client_secret", "private_key_jwt"]
+}
+
+// AppRegistrationBeginOptions parametrizes the registration begin request.
+// A zero value selects the legacy client_secret flow, preserving prior behavior.
+type AppRegistrationBeginOptions struct {
+	AuthMethod      string // "" => client_secret; core.AuthMethodPrivateKeyJWT
+	AuthAttestation string // private_key_jwt: the TEE-signed attestation JWT
+	RestoreAppID    string // when set, asks the server to re-register this existing app
+}
+
+// RequestAppRegistrationInit performs the init step of the registration flow,
+// returning a server nonce (to be embedded in a TEE-signed attestation JWT) and
+// the auth methods the server supports for this archetype.
+func RequestAppRegistrationInit(httpClient *http.Client) (*AppRegistrationInit, error) {
+	// Registration always begins against the feishu accounts host (mirrors begin).
+	endpoint := core.ResolveEndpoints(core.BrandFeishu).Accounts + PathAppRegistration
+
+	form := url.Values{}
+	form.Set("action", "init")
+	form.Set("archetype", "PersonalAgent")
+
+	req, err := http.NewRequest("POST", endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	logHTTPResponse(resp)
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("app registration init failed: read body: %w", err)
+	}
+
+	var data map[string]interface{}
+	if err := json.Unmarshal(body, &data); err != nil {
+		return nil, fmt.Errorf("app registration init failed: HTTP %d – response not JSON", resp.StatusCode)
+	}
+
+	if _, hasError := data["error"]; resp.StatusCode >= 400 || hasError {
+		msg := getStr(data, "error_description")
+		if msg == "" {
+			msg = getStr(data, "error")
+		}
+		if msg == "" {
+			msg = "Unknown error"
+		}
+		return nil, fmt.Errorf("app registration init failed: %s", msg)
+	}
+
+	out := &AppRegistrationInit{Nonce: getStr(data, "nonce")}
+	if methods, ok := data["supported_auth_methods"].([]interface{}); ok {
+		for _, m := range methods {
+			if s, ok := m.(string); ok {
+				out.SupportedAuthMethods = append(out.SupportedAuthMethods, s)
+			}
+		}
+	}
+	if out.Nonce == "" {
+		return nil, fmt.Errorf("app registration init failed: server returned no nonce")
+	}
+	return out, nil
+}
+
+// RequestAppRegistration initiates the app registration device flow (begin step).
+func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, opts AppRegistrationBeginOptions, errOut io.Writer) (*AppRegistrationResponse, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -49,11 +127,24 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOu
 	regEp := core.ResolveEndpoints(core.BrandFeishu) // registration begin always uses feishu
 	endpoint := regEp.Accounts + PathAppRegistration
 
+	authMethod := opts.AuthMethod
+	if authMethod == "" {
+		authMethod = core.AuthMethodClientSecret
+	}
+
 	form := url.Values{}
 	form.Set("action", "begin")
 	form.Set("archetype", "PersonalAgent")
-	form.Set("auth_method", "client_secret")
+	form.Set("auth_method", authMethod)
 	form.Set("request_user_info", "open_id tenant_brand")
+	if opts.AuthAttestation != "" {
+		form.Set("auth_attestation", opts.AuthAttestation)
+	}
+	// Restore flow: carry the existing app id so the server re-registers it
+	// rather than creating a new app.
+	if opts.RestoreAppID != "" {
+		form.Set("app_id", opts.RestoreAppID)
+	}
 
 	req, err := http.NewRequest("POST", endpoint, strings.NewReader(form.Encode()))
 	if err != nil {
@@ -95,7 +186,24 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOu
 
 	userCode := getStr(data, "user_code")
 	verificationUri := getStr(data, "verification_uri")
-	verificationUriComplete := fmt.Sprintf("%s/page/cli?user_code=%s", ep.Open, userCode)
+	// Prefer the server-provided complete URL (currently /page/launcher); fall
+	// back to building it from verification_uri, then to /page/launcher. The old
+	// hard-coded /page/cli is stale — the server now returns /page/launcher.
+	verificationUriComplete := getStr(data, "verification_uri_complete")
+	if verificationUriComplete == "" {
+		base := verificationUri
+		if base == "" {
+			base = ep.Open + "/page/launcher"
+		}
+		// The server may return verification_uri with its own query (e.g.
+		// client_id when registering against an existing app), so join with
+		// the same ?/& logic as BuildVerificationURL.
+		sep := "?"
+		if strings.Contains(base, "?") {
+			sep = "&"
+		}
+		verificationUriComplete = base + sep + "user_code=" + url.QueryEscape(userCode)
+	}
 
 	return &AppRegistrationResponse{
 		DeviceCode:              getStr(data, "device_code"),
@@ -107,6 +215,26 @@ func RequestAppRegistration(httpClient *http.Client, brand core.LarkBrand, errOu
 	}, nil
 }
 
+// parseAuthMethods normalizes the poll response `auth_method` field, which the
+// server returns as a JSON array of strings (e.g. ["private_key_jwt"]) — or, on
+// some variants, a single space-separated string.
+func parseAuthMethods(v interface{}) []string {
+	switch t := v.(type) {
+	case []interface{}:
+		out := make([]string, 0, len(t))
+		for _, m := range t {
+			if s, ok := m.(string); ok && s != "" {
+				out = append(out, s)
+			}
+		}
+		return out
+	case string:
+		return strings.Fields(t)
+	default:
+		return nil
+	}
+}
+
 // BuildVerificationURL appends CLI tracking parameters to the verification URL.
 func BuildVerificationURL(baseURL, cliVersion string) string {
 	sep := "&"
@@ -187,6 +315,7 @@ func PollAppRegistration(ctx context.Context, httpClient *http.Client, brand cor
 			result := &AppRegistrationResult{
 				ClientID:     getStr(data, "client_id"),
 				ClientSecret: getStr(data, "client_secret"),
+				AuthMethods:  parseAuthMethods(data["auth_method"]),
 			}
 			if userInfoRaw, ok := data["user_info"].(map[string]interface{}); ok {
 				result.UserInfo = &AppRegUserInfo{

internal/auth/app_registration_test.go

@@ -4,8 +4,14 @@
 package auth
 
 import (
+	"io"
+	"net/http"
+	"net/url"
+	"slices"
+	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/internal/core"
 	"github.com/smartystreets/goconvey/convey"
 )
 
@@ -31,3 +37,184 @@ func Test_BuildVerificationURL(t *testing.T) {
 		})
 	})
 }
+
+// captureClient returns an http.Client that records the last request's form body
+// and replies with the given JSON payload.
+func captureClient(gotBody *url.Values, respJSON string) *http.Client {
+	return &http.Client{
+		Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+			if req.Body != nil {
+				b, _ := io.ReadAll(req.Body)
+				v, _ := url.ParseQuery(string(b))
+				*gotBody = v
+			}
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     make(http.Header),
+				Body:       io.NopCloser(strings.NewReader(respJSON)),
+			}, nil
+		}),
+	}
+}
+
+func TestRequestAppRegistrationInit_ParsesNonceAndMethods(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"nonce":"n-123","supported_auth_methods":["client_secret","private_key_jwt"]}`)
+
+	out, err := RequestAppRegistrationInit(hc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Nonce != "n-123" {
+		t.Errorf("nonce = %q, want n-123", out.Nonce)
+	}
+	if len(out.SupportedAuthMethods) != 2 || out.SupportedAuthMethods[1] != "private_key_jwt" {
+		t.Errorf("methods = %v", out.SupportedAuthMethods)
+	}
+	if body.Get("action") != "init" {
+		t.Errorf("action = %q, want init", body.Get("action"))
+	}
+}
+
+func TestRequestAppRegistrationInit_ErrorOnMissingNonce(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"supported_auth_methods":["client_secret"]}`)
+	if _, err := RequestAppRegistrationInit(hc); err == nil {
+		t.Fatal("expected error when server returns no nonce")
+	}
+}
+
+// TestRequestAppRegistrationInit_EmptySupportedAuthMethods covers the older-server
+// back-compat path: an empty supported_auth_methods array parses to an empty
+// slice, so the init guard in cmd/config/init_interactive.go
+// (`len(SupportedAuthMethods) > 0 && !slices.Contains(...)`) stays false and does
+// NOT reject the requested private_key_jwt. This aligns with
+// resolveFinalAuthMethod(nil/[], private_key_jwt) == private_key_jwt
+// (see cmd/config TestResolveFinalAuthMethod).
+func TestRequestAppRegistrationInit_EmptySupportedAuthMethods(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, `{"nonce":"n-1","supported_auth_methods":[]}`)
+
+	out, err := RequestAppRegistrationInit(hc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out.Nonce != "n-1" {
+		t.Errorf("nonce = %q, want n-1", out.Nonce)
+	}
+	if len(out.SupportedAuthMethods) != 0 {
+		t.Errorf("SupportedAuthMethods = %v, want empty", out.SupportedAuthMethods)
+	}
+	// Reproduce the init guard expression on the real parsed result: an empty
+	// slice must NOT reject private_key_jwt.
+	rejected := len(out.SupportedAuthMethods) > 0 &&
+		!slices.Contains(out.SupportedAuthMethods, core.AuthMethodPrivateKeyJWT)
+	if rejected {
+		t.Error("empty SupportedAuthMethods must allow private_key_jwt (older-server back-compat)")
+	}
+}
+
+const beginRespJSON = `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`
+
+func TestRequestAppRegistration_BeginDefaultsToClientSecret(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	if _, err := RequestAppRegistration(hc, core.BrandFeishu, AppRegistrationBeginOptions{}, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("action") != "begin" {
+		t.Errorf("action = %q", body.Get("action"))
+	}
+	if body.Get("auth_method") != "client_secret" {
+		t.Errorf("auth_method = %q, want client_secret (default)", body.Get("auth_method"))
+	}
+	if body.Has("auth_attestation") {
+		t.Errorf("auth_attestation should be absent for client_secret, got %q", body.Get("auth_attestation"))
+	}
+	// Normal (non-restore) begin must NOT carry app_id.
+	if body.Has("app_id") {
+		t.Errorf("app_id should be absent when RestoreAppID is empty, got %q", body.Get("app_id"))
+	}
+}
+
+// TestRequestAppRegistration_BeginRestoreAppID verifies the restore flow sends the
+// existing app id on begin so the server re-registers that app.
+func TestRequestAppRegistration_BeginRestoreAppID(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	opts := AppRegistrationBeginOptions{RestoreAppID: "cli_restore_me"}
+	if _, err := RequestAppRegistration(hc, core.BrandFeishu, opts, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("action") != "begin" {
+		t.Errorf("action = %q, want begin", body.Get("action"))
+	}
+	if body.Get("app_id") != "cli_restore_me" {
+		t.Errorf("app_id = %q, want cli_restore_me", body.Get("app_id"))
+	}
+}
+
+func TestRequestAppRegistration_VerificationURICompleteFallback(t *testing.T) {
+	cases := []struct {
+		name string
+		resp string
+		want string
+	}{
+		{
+			name: "bare verification_uri",
+			resp: `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`,
+			want: "https://example/verify?user_code=uc",
+		},
+		{
+			name: "verification_uri with existing query",
+			resp: `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify?client_id=cli_x","expires_in":300,"interval":5}`,
+			want: "https://example/verify?client_id=cli_x&user_code=uc",
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			var body url.Values
+			hc := captureClient(&body, tc.resp)
+			got, err := RequestAppRegistration(hc, core.BrandFeishu, AppRegistrationBeginOptions{}, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got.VerificationUriComplete != tc.want {
+				t.Errorf("VerificationUriComplete = %q, want %q", got.VerificationUriComplete, tc.want)
+			}
+		})
+	}
+}
+
+func TestParseAuthMethods(t *testing.T) {
+	if got := parseAuthMethods([]interface{}{"private_key_jwt", "client_secret"}); len(got) != 2 || got[0] != "private_key_jwt" {
+		t.Errorf("array form = %v", got)
+	}
+	if got := parseAuthMethods("client_secret private_key_jwt"); len(got) != 2 || got[1] != "private_key_jwt" {
+		t.Errorf("string form = %v", got)
+	}
+	if got := parseAuthMethods(nil); got != nil {
+		t.Errorf("nil form = %v, want nil", got)
+	}
+}
+
+func TestRequestAppRegistration_BeginPrivateKeyJWT(t *testing.T) {
+	var body url.Values
+	hc := captureClient(&body, beginRespJSON)
+
+	opts := AppRegistrationBeginOptions{
+		AuthMethod:      core.AuthMethodPrivateKeyJWT,
+		AuthAttestation: "header.claims.sig",
+	}
+	if _, err := RequestAppRegistration(hc, core.BrandFeishu, opts, nil); err != nil {
+		t.Fatal(err)
+	}
+	if body.Get("auth_method") != "private_key_jwt" {
+		t.Errorf("auth_method = %q, want private_key_jwt", body.Get("auth_method"))
+	}
+	if body.Get("auth_attestation") != "header.claims.sig" {
+		t.Errorf("auth_attestation = %q", body.Get("auth_attestation"))
+	}
+}

internal/auth/client_auth.go

@@ -0,0 +1,63 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"time"
+
+	"github.com/larksuite/cli/internal/auth/jwt"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// ClientAuth describes how to authenticate the OAuth client at the token
+// endpoint: with a client_secret (default) or a TEE-signed client_assertion
+// (private_key_jwt).
+type ClientAuth struct {
+	AppID      string
+	AppSecret  string
+	AuthMethod string // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	Signer     keysigner.Signer
+	KeyLabel   string
+}
+
+// ClientAuthFromConfig builds a ClientAuth from resolved config, picking up the
+// active key signer for private_key_jwt apps.
+func ClientAuthFromConfig(cfg *core.CliConfig) ClientAuth {
+	if cfg == nil {
+		return ClientAuth{}
+	}
+	return ClientAuth{
+		AppID:      cfg.AppID,
+		AppSecret:  cfg.AppSecret,
+		AuthMethod: cfg.AuthMethod,
+		KeyLabel:   cfg.KeyLabel,
+		Signer:     keysigner.Active(),
+	}
+}
+
+func (c ClientAuth) isPrivateKeyJWT() bool { return c.AuthMethod == core.AuthMethodPrivateKeyJWT }
+
+// applyClientAssertion adds client_assertion(+type) to a token-endpoint form for
+// private_key_jwt and returns true. For client_secret it returns false, leaving
+// the caller to apply its own secret-based authentication. audience is the token
+// endpoint URL (the assertion's aud claim).
+func (c ClientAuth) applyClientAssertion(ctx context.Context, form url.Values, audience string) (bool, error) {
+	if !c.isPrivateKeyJWT() {
+		return false, nil
+	}
+	if c.Signer == nil {
+		return false, fmt.Errorf("private_key_jwt requires a key signer, but none is available on this build")
+	}
+	assertion, err := jwt.SignClientAssertion(ctx, c.Signer, keysigner.KeyRef{Label: c.KeyLabel}, c.AppID, audience, time.Now())
+	if err != nil {
+		return false, err
+	}
+	form.Set("client_assertion_type", jwt.ClientAssertionType)
+	form.Set("client_assertion", assertion)
+	return true, nil
+}

internal/auth/client_auth_test.go

@@ -0,0 +1,109 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package auth
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"net/url"
+	"testing"
+
+	"github.com/larksuite/cli/internal/auth/jwt"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// fakeAuthSigner is a real in-memory ECDSA P-256 signer for client-auth tests.
+type fakeAuthSigner struct{ key *ecdsa.PrivateKey }
+
+func newFakeAuthSigner(t *testing.T) *fakeAuthSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &fakeAuthSigner{key: k}
+}
+
+func (f *fakeAuthSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeAuthSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeAuthSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(rand.Reader, f.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
+func TestClientAuth_applyClientAssertion_ClientSecret(t *testing.T) {
+	ca := ClientAuth{AppID: "cli_a", AppSecret: "sec"} // AuthMethod "" => client_secret
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "https://aud/token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if used {
+		t.Error("client_secret must not produce a client_assertion")
+	}
+	if form.Has("client_assertion") || form.Has("client_assertion_type") {
+		t.Errorf("form should be untouched, got %v", form)
+	}
+}
+
+func TestClientAuth_applyClientAssertion_PrivateKeyJWT(t *testing.T) {
+	ca := ClientAuth{
+		AppID:      "cli_a",
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		Signer:     newFakeAuthSigner(t),
+		KeyLabel:   "k",
+	}
+	form := url.Values{}
+	used, err := ca.applyClientAssertion(context.Background(), form, "https://accounts.feishu.cn/open-apis/authen/v2/oauth/token")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !used {
+		t.Fatal("expected client_assertion to be applied")
+	}
+	if form.Get("client_assertion_type") != jwt.ClientAssertionType {
+		t.Errorf("client_assertion_type = %q", form.Get("client_assertion_type"))
+	}
+	if form.Get("client_assertion") == "" {
+		t.Error("client_assertion is empty")
+	}
+	if form.Has("client_secret") {
+		t.Error("client_secret must NOT be present for private_key_jwt")
+	}
+}
+
+func TestClientAuth_applyClientAssertion_NilSigner(t *testing.T) {
+	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT} // Signer nil
+	if _, err := ca.applyClientAssertion(context.Background(), url.Values{}, "aud"); err == nil {
+		t.Fatal("expected error when private_key_jwt has no signer")
+	}
+}
+
+func TestClientAuthFromConfig(t *testing.T) {
+	ca := ClientAuthFromConfig(&core.CliConfig{
+		AppID:      "cli_x",
+		AppSecret:  "s",
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel:   "label-1",
+	})
+	if ca.AppID != "cli_x" || ca.AppSecret != "s" || ca.AuthMethod != core.AuthMethodPrivateKeyJWT || ca.KeyLabel != "label-1" {
+		t.Errorf("ClientAuth = %+v", ca)
+	}
+}

internal/auth/device_flow.go

@@ -62,7 +62,7 @@ func ResolveOAuthEndpoints(brand core.LarkBrand) OAuthEndpoints {
 }
 
 // RequestDeviceAuthorization requests a device authorization code.
-func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
+func RequestDeviceAuthorization(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, scope string, errOut io.Writer) (*DeviceAuthResponse, error) {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -77,18 +77,26 @@ func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string
 		}
 	}
 
-	basicAuth := base64.StdEncoding.EncodeToString([]byte(appId + ":" + appSecret))
-
 	form := url.Values{}
-	form.Set("client_id", appId)
+	form.Set("client_id", ca.AppID)
 	form.Set("scope", scope)
 
-	req, err := http.NewRequest("POST", endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
+	// private_key_jwt authenticates the client with a signed assertion in the
+	// body; client_secret uses HTTP Basic.
+	usedAssertion, err := ca.applyClientAssertion(ctx, form, core.OpenAPIAudience(brand))
+	if err != nil {
+		return nil, err
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", endpoints.DeviceAuthorization, strings.NewReader(form.Encode()))
 	if err != nil {
 		return nil, err
 	}
 	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
-	req.Header.Set("Authorization", "Basic "+basicAuth)
+	if !usedAssertion {
+		basicAuth := base64.StdEncoding.EncodeToString([]byte(ca.AppID + ":" + ca.AppSecret))
+		req.Header.Set("Authorization", "Basic "+basicAuth)
+	}
 
 	resp, err := httpClient.Do(req)
 	if err != nil {
@@ -139,7 +147,7 @@ func RequestDeviceAuthorization(httpClient *http.Client, appId, appSecret string
 }
 
 // PollDeviceToken polls the token endpoint until authorization completes or times out.
-func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSecret string, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
+func PollDeviceToken(ctx context.Context, httpClient *http.Client, ca ClientAuth, brand core.LarkBrand, deviceCode string, interval, expiresIn int, errOut io.Writer) *DeviceFlowResult {
 	if errOut == nil {
 		errOut = io.Discard
 	}
@@ -171,10 +179,16 @@ func PollDeviceToken(ctx context.Context, httpClient *http.Client, appId, appSec
 		form := url.Values{}
 		form.Set("grant_type", "urn:ietf:params:oauth:grant-type:device_code")
 		form.Set("device_code", deviceCode)
-		form.Set("client_id", appId)
-		form.Set("client_secret", appSecret)
+		form.Set("client_id", ca.AppID)
+		usedAssertion, caErr := ca.applyClientAssertion(ctx, form, core.OpenAPIAudience(brand))
+		if caErr != nil {
+			return &DeviceFlowResult{OK: false, Error: "invalid_client", Message: caErr.Error()}
+		}
+		if !usedAssertion {
+			form.Set("client_secret", ca.AppSecret)
+		}
 
-		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
+		req, err := http.NewRequestWithContext(ctx, "POST", endpoints.Token, strings.NewReader(form.Encode()))
 		if err != nil {
 			continue
 		}

internal/auth/device_flow_test.go

@@ -7,8 +7,10 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"io"
 	"log"
 	"net/http"
+	"net/url"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -83,7 +85,7 @@ func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
 	})
 	t.Cleanup(restore)
 
-	_, err := RequestDeviceAuthorization(httpmock.NewClient(reg), "cli_a", "secret_b", core.BrandFeishu, "", nil)
+	_, err := RequestDeviceAuthorization(context.Background(), httpmock.NewClient(reg), ClientAuth{AppID: "cli_a", AppSecret: "secret_b"}, core.BrandFeishu, "", nil)
 	if err != nil {
 		t.Fatalf("RequestDeviceAuthorization() error: %v", err)
 	}
@@ -106,6 +108,66 @@ func TestRequestDeviceAuthorization_LogsResponse(t *testing.T) {
 	}
 }
 
+// captureRT records the last request + body and returns a canned device-auth response.
+func captureDeviceAuthClient(gotReq **http.Request, gotBody *string, respJSON string) *http.Client {
+	return &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		*gotReq = req
+		if req.Body != nil {
+			b, _ := io.ReadAll(req.Body)
+			*gotBody = string(b)
+		}
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader(respJSON)),
+		}, nil
+	})}
+}
+
+const deviceAuthRespJSON = `{"device_code":"dc","user_code":"uc","verification_uri":"https://example/verify","expires_in":300,"interval":5}`
+
+func TestRequestDeviceAuthorization_PrivateKeyJWT_UsesAssertionNotBasic(t *testing.T) {
+	var req *http.Request
+	var body string
+	client := captureDeviceAuthClient(&req, &body, deviceAuthRespJSON)
+
+	ca := ClientAuth{AppID: "cli_a", AuthMethod: core.AuthMethodPrivateKeyJWT, Signer: newFakeAuthSigner(t), KeyLabel: "k"}
+	if _, err := RequestDeviceAuthorization(context.Background(), client, ca, core.BrandFeishu, "im:message:send", nil); err != nil {
+		t.Fatal(err)
+	}
+	if req.Header.Get("Authorization") != "" {
+		t.Errorf("private_key_jwt must NOT send Basic auth, got %q", req.Header.Get("Authorization"))
+	}
+	form, _ := url.ParseQuery(body)
+	if form.Get("client_assertion") == "" {
+		t.Error("missing client_assertion")
+	}
+	if form.Get("client_assertion_type") != "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" {
+		t.Errorf("client_assertion_type = %q", form.Get("client_assertion_type"))
+	}
+	if form.Has("client_secret") {
+		t.Error("client_secret must not be present for private_key_jwt")
+	}
+}
+
+func TestRequestDeviceAuthorization_ClientSecret_UsesBasic(t *testing.T) {
+	var req *http.Request
+	var body string
+	client := captureDeviceAuthClient(&req, &body, deviceAuthRespJSON)
+
+	ca := ClientAuth{AppID: "cli_a", AppSecret: "sec"} // client_secret
+	if _, err := RequestDeviceAuthorization(context.Background(), client, ca, core.BrandFeishu, "", nil); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.HasPrefix(req.Header.Get("Authorization"), "Basic ") {
+		t.Errorf("client_secret should use Basic auth, got %q", req.Header.Get("Authorization"))
+	}
+	form, _ := url.ParseQuery(body)
+	if form.Has("client_assertion") {
+		t.Error("client_secret must not send a client_assertion")
+	}
+}
+
 // TestFormatAuthCmdline_TruncatesExtraArgs verifies that long command lines are truncated.
 func TestFormatAuthCmdline_TruncatesExtraArgs(t *testing.T) {
 	got := keychain.FormatAuthCmdline([]string{
@@ -205,7 +267,7 @@ func TestPollDeviceToken_DefaultsZeroIntervalToFiveSeconds(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
 	t.Cleanup(cancel)
 
-	result := PollDeviceToken(ctx, client, "cli_a", "secret_b", core.BrandFeishu, "device-code", 0, 10, nil)
+	result := PollDeviceToken(ctx, client, ClientAuth{AppID: "cli_a", AppSecret: "secret_b"}, core.BrandFeishu, "device-code", 0, 10, nil)
 	if result == nil {
 		t.Fatal("PollDeviceToken() returned nil result")
 	}

internal/auth/jwt/jwt.go

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package jwt builds compact JWS tokens signed by a keysigner.Signer.
+//
+// It deliberately depends only on the standard library plus the existing
+// google/uuid dependency — no third-party JWT library is introduced, keeping
+// go.mod free of new dependencies. The actual signing (and, for ECDSA, the
+// ASN.1->r||s conversion) is delegated to the Signer implementation.
+package jwt
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }
+
+// buildSignedJWT builds a compact JWS:
+//
+//	base64url(header).base64url(claims).base64url(signature)
+//
+// alg is written into the header (it is part of the signed input) and verified
+// against the alg the signer reports, guarding against a header/key mismatch.
+// typ defaults to "JWT": the server's client_assertion generalizedValidation
+// REQUIRES `typ == "JWT"` (rejects otherwise with "malformed client assertion
+// jwt"), even though the spec examples (§8.1/§8.2) show only alg.
+func buildSignedJWT(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, alg string, header, claims map[string]any) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	if header == nil {
+		header = map[string]any{}
+	}
+	header["alg"] = alg
+	if _, ok := header["typ"]; !ok {
+		header["typ"] = "JWT"
+	}
+
+	hb, err := json.Marshal(header)
+	if err != nil {
+		return "", fmt.Errorf("jwt: marshal header: %w", err)
+	}
+	cb, err := json.Marshal(claims)
+	if err != nil {
+		return "", fmt.Errorf("jwt: marshal claims: %w", err)
+	}
+
+	signingInput := b64(hb) + "." + b64(cb)
+	sig, gotAlg, err := signer.Sign(ctx, ref, []byte(signingInput))
+	if err != nil {
+		return "", fmt.Errorf("jwt: sign: %w", err)
+	}
+	if gotAlg != alg {
+		return "", fmt.Errorf("jwt: signer alg %q does not match header alg %q", gotAlg, alg)
+	}
+	return signingInput + "." + b64(sig), nil
+}
+
+// newJTI returns a random unique token identifier.
+func newJTI() string { return uuid.NewString() }
+
+// attestationTTL bounds the attestation JWT's lifetime. The init nonce (60s,
+// single-use) is the real anti-replay constraint; this is a modest margin for
+// clock skew on top of the immediate init→sign→begin round-trip.
+const attestationTTL = 2 * time.Minute
+
+// attestationClaims builds the registration attestation claim set per the App
+// Registration JWT spec: jti, iat, exp (all required) and the init-issued nonce.
+func attestationClaims(nonce string, now time.Time) map[string]any {
+	return map[string]any{
+		"jti":   newJTI(),
+		"iat":   now.Unix(),
+		"exp":   now.Add(attestationTTL).Unix(),
+		"nonce": nonce,
+	}
+}
+
+// clientAssertionClaims builds an RFC 7523 client_assertion claim set used to
+// mint tokens in place of client_secret. aud is the brand's token endpoint URL.
+func clientAssertionClaims(clientID, aud string, now time.Time, ttl time.Duration) map[string]any {
+	return map[string]any{
+		"iss": clientID,
+		"sub": clientID,
+		"aud": aud,
+		"iat": now.Unix(),
+		"exp": now.Add(ttl).Unix(),
+		"jti": newJTI(),
+	}
+}
+
+// ClientAssertionType is the RFC 7523 client_assertion_type value used for JWT
+// bearer client authentication at the token endpoint.
+const ClientAssertionType = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+// defaultAssertionTTL bounds a client_assertion's lifetime.
+const defaultAssertionTTL = 5 * time.Minute
+
+// SignAttestation signs the registration attestation JWT. The public key is
+// embedded in the JWS "jwk" header so the registration backend can bind it to
+// the app during action=begin; the claims carry the server nonce as a
+// proof-of-possession challenge.
+func SignAttestation(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, nonce string, now time.Time) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	pub, err := signer.EnsureKey(ctx, ref)
+	if err != nil {
+		return "", fmt.Errorf("jwt: ensure key: %w", err)
+	}
+	alg, err := keysigner.AlgForKey(pub)
+	if err != nil {
+		return "", err
+	}
+	jwk, err := keysigner.PublicKeyJWK(pub)
+	if err != nil {
+		return "", err
+	}
+	return buildSignedJWT(ctx, signer, ref, alg, map[string]any{"jwk": jwk}, attestationClaims(nonce, now))
+}
+
+// SignClientAssertion mints a short-lived RFC 7523 client_assertion: it reads the
+// registered key (it must already exist — bound at registration; a missing key is
+// an error, not a reason to create a new unbound one), derives the JWS alg from
+// the public key, and signs an assertion whose audience is the brand's Open API
+// host. The server, holding the public key bound at registration, verifies it in
+// place of client_secret. The assertion header carries only alg (no jwk/kid);
+// the server locates the key via iss/sub = client_id.
+//
+// This is the model-independent glue: the assertion JWT is identical whether the
+// server augments an existing grant (device_code/refresh_token) with client
+// authentication or uses a dedicated jwt-bearer grant — only where the caller
+// attaches it differs.
+func SignClientAssertion(ctx context.Context, signer keysigner.Signer, ref keysigner.KeyRef, clientID, audience string, now time.Time) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("jwt: no signer available (private_key_jwt unsupported on this build)")
+	}
+	pub, err := signer.PublicKey(ctx, ref)
+	if err != nil {
+		return "", fmt.Errorf("jwt: public key: %w", err)
+	}
+	alg, err := keysigner.AlgForKey(pub)
+	if err != nil {
+		return "", err
+	}
+	return buildSignedJWT(ctx, signer, ref, alg, map[string]any{}, clientAssertionClaims(clientID, audience, now, defaultAssertionTTL))
+}

internal/auth/jwt/jwt_test.go

@@ -0,0 +1,254 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package jwt
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
+	"math/big"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/internal/keysigner"
+)
+
+// fakeSigner is a real in-memory ECDSA P-256 signer, so tests exercise the full
+// JWS path and the produced token is actually cryptographically verifiable.
+type fakeSigner struct{ key *ecdsa.PrivateKey }
+
+func newFakeSigner(t *testing.T) *fakeSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &fakeSigner{key: k}
+}
+
+func (f *fakeSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(rand.Reader, f.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	// JOSE ES256: fixed-width big-endian r||s (32 bytes each for P-256).
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
+func TestBuildSignedJWT_VerifiableES256(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+
+	tok, err := buildSignedJWT(context.Background(), f, keysigner.KeyRef{Label: "x"}, keysigner.AlgES256,
+		map[string]any{}, clientAssertionClaims("cli_app", "https://accounts.example/token", now, 5*time.Minute))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 JWS parts, got %d", len(parts))
+	}
+
+	hb, err := base64.RawURLEncoding.DecodeString(parts[0])
+	if err != nil {
+		t.Fatalf("header not base64url: %v", err)
+	}
+	var hdr map[string]any
+	if err := json.Unmarshal(hb, &hdr); err != nil {
+		t.Fatal(err)
+	}
+	if hdr["alg"] != "ES256" || hdr["typ"] != "JWT" {
+		t.Errorf("header = %v, want alg=ES256 typ=JWT (server generalizedValidation requires typ)", hdr)
+	}
+
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["iss"] != "cli_app" || claims["sub"] != "cli_app" || claims["aud"] != "https://accounts.example/token" {
+		t.Errorf("claims = %v", claims)
+	}
+
+	// Cryptographically verify the signature against the signing input.
+	sig, err := base64.RawURLEncoding.DecodeString(parts[2])
+	if err != nil {
+		t.Fatalf("sig not base64url: %v", err)
+	}
+	if len(sig) != 64 {
+		t.Fatalf("ES256 sig len = %d, want 64", len(sig))
+	}
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("signature did not verify")
+	}
+}
+
+func TestBuildSignedJWT_NilSigner(t *testing.T) {
+	if _, err := buildSignedJWT(context.Background(), nil, keysigner.KeyRef{}, "ES256", nil, nil); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestBuildSignedJWT_AlgMismatch(t *testing.T) {
+	f := newFakeSigner(t) // always reports ES256
+	if _, err := buildSignedJWT(context.Background(), f, keysigner.KeyRef{}, keysigner.AlgRS256, nil, nil); err == nil {
+		t.Fatal("expected error when header alg != signer alg")
+	}
+}
+
+func TestBuildSignedJWT_MarshalErrors(t *testing.T) {
+	f := newFakeSigner(t)
+	ctx := context.Background()
+
+	_, err := buildSignedJWT(ctx, f, keysigner.KeyRef{}, keysigner.AlgES256,
+		map[string]any{"bad": func() {}}, nil)
+	if err == nil || !strings.Contains(err.Error(), "jwt: marshal header") {
+		t.Fatalf("header marshal error = %v, want prefix %q", err, "jwt: marshal header")
+	}
+
+	_, err = buildSignedJWT(ctx, f, keysigner.KeyRef{}, keysigner.AlgES256,
+		nil, map[string]any{"bad": make(chan int)})
+	if err == nil || !strings.Contains(err.Error(), "jwt: marshal claims") {
+		t.Fatalf("claims marshal error = %v, want prefix %q", err, "jwt: marshal claims")
+	}
+}
+
+func TestSignClientAssertion(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+	const aud = "https://accounts.feishu.cn/open-apis/authen/v2/oauth/token"
+
+	tok, err := SignClientAssertion(context.Background(), f, keysigner.KeyRef{Label: "k"}, "cli_app", aud, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 parts, got %d", len(parts))
+	}
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["iss"] != "cli_app" || claims["aud"] != aud {
+		t.Errorf("claims = %v", claims)
+	}
+
+	// Signature must verify against the key's public half.
+	sig, _ := base64.RawURLEncoding.DecodeString(parts[2])
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("client_assertion signature did not verify")
+	}
+}
+
+func TestSignClientAssertion_NilSigner(t *testing.T) {
+	if _, err := SignClientAssertion(context.Background(), nil, keysigner.KeyRef{}, "cli_app", "aud", time.Unix(0, 0)); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestSignAttestation(t *testing.T) {
+	f := newFakeSigner(t)
+	now := time.Unix(1700000000, 0)
+
+	tok, err := SignAttestation(context.Background(), f, keysigner.KeyRef{Label: "k"}, "nonce-abc", now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	parts := strings.Split(tok, ".")
+	if len(parts) != 3 {
+		t.Fatalf("want 3 parts, got %d", len(parts))
+	}
+
+	hb, _ := base64.RawURLEncoding.DecodeString(parts[0])
+	var hdr map[string]any
+	if err := json.Unmarshal(hb, &hdr); err != nil {
+		t.Fatal(err)
+	}
+	jwk, ok := hdr["jwk"].(map[string]any)
+	if !ok {
+		t.Fatalf("attestation header missing jwk: %v", hdr)
+	}
+	if jwk["kty"] != "EC" || jwk["crv"] != "P-256" || jwk["use"] != "sig" {
+		t.Errorf("jwk = %v", jwk)
+	}
+
+	cb, _ := base64.RawURLEncoding.DecodeString(parts[1])
+	var claims map[string]any
+	if err := json.Unmarshal(cb, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["nonce"] != "nonce-abc" {
+		t.Errorf("nonce = %v", claims["nonce"])
+	}
+	// jti, iat, exp are all required by the attestation spec.
+	iat, iatOK := claims["iat"].(float64)
+	exp, expOK := claims["exp"].(float64)
+	if !iatOK || !expOK || exp <= iat {
+		t.Errorf("claims iat/exp invalid: iat=%v exp=%v", claims["iat"], claims["exp"])
+	}
+	if jti, _ := claims["jti"].(string); jti == "" {
+		t.Error("claims jti empty")
+	}
+
+	// Signature verifies against the embedded key.
+	sig, _ := base64.RawURLEncoding.DecodeString(parts[2])
+	r := new(big.Int).SetBytes(sig[:32])
+	s := new(big.Int).SetBytes(sig[32:])
+	h := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
+	if !ecdsa.Verify(f.key.Public().(*ecdsa.PublicKey), h[:], r, s) {
+		t.Error("attestation signature did not verify")
+	}
+}
+
+func TestSignAttestation_NilSigner(t *testing.T) {
+	if _, err := SignAttestation(context.Background(), nil, keysigner.KeyRef{}, "n", time.Unix(0, 0)); err == nil {
+		t.Fatal("expected error for nil signer")
+	}
+}
+
+func TestClaimFactories(t *testing.T) {
+	now := time.Unix(1700000000, 0)
+
+	a := attestationClaims("nonce-xyz", now)
+	if a["nonce"] != "nonce-xyz" || a["iat"] != now.Unix() {
+		t.Errorf("attestation claims = %v", a)
+	}
+	if a["exp"] != now.Add(attestationTTL).Unix() {
+		t.Errorf("attestation exp = %v, want %v", a["exp"], now.Add(attestationTTL).Unix())
+	}
+	if jti, _ := a["jti"].(string); jti == "" {
+		t.Error("attestation jti empty")
+	}
+
+	c := clientAssertionClaims("cli_app", "aud", now, time.Minute)
+	if c["exp"].(int64) != now.Add(time.Minute).Unix() {
+		t.Errorf("client_assertion exp = %v", c["exp"])
+	}
+}

internal/auth/uat_client.go

@@ -21,6 +21,7 @@ import (
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/errclass"
+	"github.com/larksuite/cli/internal/keysigner"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -37,7 +38,10 @@ type UATCallOptions struct {
 	AppId      string
 	AppSecret  string
 	Domain     core.LarkBrand
-	ErrOut     io.Writer // diagnostic/status output (caller injects f.IOStreams.ErrOut)
+	AuthMethod string           // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	KeyLabel   string           // TEE key handle for private_key_jwt
+	Signer     keysigner.Signer // active signer for private_key_jwt
+	ErrOut     io.Writer        // diagnostic/status output (caller injects f.IOStreams.ErrOut)
 }
 
 // UATStatus represents the status of a user access token.
@@ -61,6 +65,9 @@ func NewUATCallOptions(cfg *core.CliConfig, errOut io.Writer) UATCallOptions {
 		AppId:      cfg.AppID,
 		AppSecret:  cfg.AppSecret,
 		Domain:     cfg.Brand,
+		AuthMethod: cfg.AuthMethod,
+		KeyLabel:   cfg.KeyLabel,
+		Signer:     keysigner.Active(),
 		ErrOut:     errOut,
 	}
 }
@@ -193,7 +200,14 @@ func doRefreshToken(httpClient *http.Client, opts UATCallOptions, stored *Stored
 		form.Set("grant_type", "refresh_token")
 		form.Set("refresh_token", stored.RefreshToken)
 		form.Set("client_id", opts.AppId)
-		form.Set("client_secret", opts.AppSecret)
+		ca := ClientAuth{AppID: opts.AppId, AppSecret: opts.AppSecret, AuthMethod: opts.AuthMethod, Signer: opts.Signer, KeyLabel: opts.KeyLabel}
+		usedAssertion, caErr := ca.applyClientAssertion(context.Background(), form, core.OpenAPIAudience(opts.Domain))
+		if caErr != nil {
+			return nil, caErr
+		}
+		if !usedAssertion {
+			form.Set("client_secret", opts.AppSecret)
+		}
 
 		req, err := http.NewRequest("POST", endpoints.Token, strings.NewReader(form.Encode()))
 		if err != nil {

internal/auth/uat_client_options_test.go

@@ -38,3 +38,23 @@ func TestNewUATCallOptions(t *testing.T) {
 		t.Error("ErrOut not set correctly")
 	}
 }
+
+// TestNewUATCallOptions_PrivateKeyJWT verifies the auth-method fields propagate
+// so the refresh path can mint a client_assertion instead of sending a secret.
+func TestNewUATCallOptions_PrivateKeyJWT(t *testing.T) {
+	cfg := &core.CliConfig{
+		AppID:      "cli_pk",
+		Brand:      core.BrandFeishu,
+		UserOpenId: "ou_test",
+		AuthMethod: core.AuthMethodPrivateKeyJWT,
+		KeyLabel:   "agent-key",
+	}
+	opts := NewUATCallOptions(cfg, &bytes.Buffer{})
+
+	if opts.AuthMethod != core.AuthMethodPrivateKeyJWT {
+		t.Errorf("AuthMethod = %q, want private_key_jwt", opts.AuthMethod)
+	}
+	if opts.KeyLabel != "agent-key" {
+		t.Errorf("KeyLabel = %q, want agent-key", opts.KeyLabel)
+	}
+}

internal/binding/audit.go

@@ -131,3 +131,31 @@ func requireInTrustedDirs(effectivePath string, trustedDirs []string, label stri
 	}
 	return fmt.Errorf("%s: path %q is not inside any trusted directory", label, effectivePath)
 }
+
+// auditFilePermissions rejects world/group-writable modes (always) and
+// world/group-readable modes (unless allowReadableByOthers is true, which
+// exec commands typically need for their usual 755 mode).
+func auditFilePermissions(effectivePath string, allowReadableByOthers bool, label string) error {
+	info, err := vfs.Stat(effectivePath)
+	if err != nil {
+		return fmt.Errorf("%s: cannot stat %q: %w", label, effectivePath, err)
+	}
+	mode := info.Mode().Perm()
+
+	if mode&0o002 != 0 {
+		return fmt.Errorf("%s: path %q is world-writable (mode %04o)", label, effectivePath, mode)
+	}
+	if mode&0o020 != 0 {
+		return fmt.Errorf("%s: path %q is group-writable (mode %04o)", label, effectivePath, mode)
+	}
+	if allowReadableByOthers {
+		return nil
+	}
+	if mode&0o004 != 0 {
+		return fmt.Errorf("%s: path %q is world-readable (mode %04o)", label, effectivePath, mode)
+	}
+	if mode&0o040 != 0 {
+		return fmt.Errorf("%s: path %q is group-readable (mode %04o)", label, effectivePath, mode)
+	}
+	return nil
+}

internal/binding/audit_unix.go

@@ -29,31 +29,3 @@ func checkOwnerUID(path, label string) error {
 	}
 	return nil
 }
-
-// auditFilePermissions rejects world/group-writable modes (always) and
-// world/group-readable modes (unless allowReadableByOthers is true, which
-// exec commands typically need for their usual 755 mode).
-func auditFilePermissions(effectivePath string, allowReadableByOthers bool, label string) error {
-	info, err := vfs.Stat(effectivePath)
-	if err != nil {
-		return fmt.Errorf("%s: cannot stat %q: %w", label, effectivePath, err)
-	}
-	mode := info.Mode().Perm()
-
-	if mode&0o002 != 0 {
-		return fmt.Errorf("%s: path %q is world-writable (mode %04o)", label, effectivePath, mode)
-	}
-	if mode&0o020 != 0 {
-		return fmt.Errorf("%s: path %q is group-writable (mode %04o)", label, effectivePath, mode)
-	}
-	if allowReadableByOthers {
-		return nil
-	}
-	if mode&0o004 != 0 {
-		return fmt.Errorf("%s: path %q is world-readable (mode %04o)", label, effectivePath, mode)
-	}
-	if mode&0o040 != 0 {
-		return fmt.Errorf("%s: path %q is group-readable (mode %04o)", label, effectivePath, mode)
-	}
-	return nil
-}

internal/binding/audit_windows.go

@@ -5,22 +5,7 @@
 
 package binding
 
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/internal/vfs"
-)
-
 // checkOwnerUID is a no-op on Windows where Unix UID semantics don't apply.
 func checkOwnerUID(path, label string) error {
 	return nil
 }
-
-// auditFilePermissions skips POSIX permission-bit auditing on Windows because
-// Go synthesizes mode bits from file attributes rather than NTFS ACLs.
-func auditFilePermissions(effectivePath string, allowReadableByOthers bool, label string) error {
-	if _, err := vfs.Stat(effectivePath); err != nil {
-		return fmt.Errorf("%s: cannot stat %q: %w", label, effectivePath, err)
-	}
-	return nil
-}

internal/binding/audit_windows_test.go

@@ -1,33 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-//go:build windows
-
-package binding
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-func TestAssertSecurePath_WindowsIgnoresSyntheticUnixPermissionBits(t *testing.T) {
-	dir := t.TempDir()
-	p := filepath.Join(dir, "secrets-getter.cmd")
-	if err := os.WriteFile(p, []byte("@echo off\r\n"), 0o600); err != nil {
-		t.Fatalf("write temp command: %v", err)
-	}
-
-	got, err := AssertSecurePath(AuditParams{
-		TargetPath:            p,
-		Label:                 "exec provider command",
-		AllowInsecurePath:     false,
-		AllowReadableByOthers: true,
-	})
-	if err != nil {
-		t.Fatalf("unexpected error for Windows synthetic mode bits: %v", err)
-	}
-	if got != p {
-		t.Errorf("got %q, want %q", got, p)
-	}
-}

internal/cmdutil/factory.go

@@ -48,22 +48,6 @@ type Factory struct {
 	SkillContent fs.FS // embedded skill tree (rooted at the skill list); nil when the build embeds no skills
 }
 
-type skipCredentialBootstrapKey struct{}
-
-// ContextWithCredentialBootstrapDisabled marks a command-tree build as
-// credential-free. Use it only for purely local command surfaces that must be
-// constructed without probing strict-mode, profile, or keychain state.
-func ContextWithCredentialBootstrapDisabled(ctx context.Context) context.Context {
-	return context.WithValue(ctx, skipCredentialBootstrapKey{}, true)
-}
-
-// IsCredentialBootstrapDisabled reports whether credential-backed bootstrap
-// probes must be skipped for this context.
-func IsCredentialBootstrapDisabled(ctx context.Context) bool {
-	v, _ := ctx.Value(skipCredentialBootstrapKey{}).(bool)
-	return v
-}
-
 // ResolveFileIO resolves a FileIO instance using the current execution context.
 // The provider controls whether the returned instance is fresh or cached.
 func (f *Factory) ResolveFileIO(ctx context.Context) fileio.FileIO {
@@ -125,9 +109,6 @@ func autoDetectIdentityFromHint(hint *credential.IdentityHint) core.Identity {
 }
 
 func (f *Factory) resolveIdentityHint(ctx context.Context) *credential.IdentityHint {
-	if IsCredentialBootstrapDisabled(ctx) {
-		return nil
-	}
 	if f.Credential == nil {
 		return nil
 	}
@@ -167,9 +148,6 @@ func (f *Factory) CheckIdentity(as core.Identity, supported []string) error {
 // ResolveStrictMode returns the effective strict mode by reading
 // Account.SupportedIdentities from the credential provider chain.
 func (f *Factory) ResolveStrictMode(ctx context.Context) core.StrictMode {
-	if IsCredentialBootstrapDisabled(ctx) {
-		return core.StrictModeOff
-	}
 	if f.Credential == nil {
 		return core.StrictModeOff
 	}

internal/cmdutil/iostreams.go

@@ -18,9 +18,6 @@ type IOStreams struct {
 	Out        io.Writer
 	ErrOut     io.Writer
 	IsTerminal bool
-	// OutIsTerminal reports whether Out is an interactive terminal. Mirrors
-	// IsTerminal; computed once in NewIOStreams and assignable directly in tests.
-	OutIsTerminal bool
 	// StderrIsTerminal reports whether ErrOut is an interactive terminal.
 	// Advisory warnings written to stderr (e.g. the proxy notice) gate on this
 	// so they stay out of non-interactive output (pipes, CI, agent runs).
@@ -30,24 +27,29 @@ type IOStreams struct {
 }
 
 // NewIOStreams builds an IOStreams from arbitrary readers/writers.
-// IsTerminal / OutIsTerminal / StderrIsTerminal are each derived from the
-// underlying *os.File of in / out / errOut respectively; non-file
-// readers/writers (bytes.Buffer, strings.Reader, …) yield false.
+// IsTerminal / StderrIsTerminal are derived from in's / errOut's underlying
+// *os.File, if any; non-file streams (bytes.Buffer, strings.Reader, …) yield
+// false.
 func NewIOStreams(in io.Reader, out, errOut io.Writer) *IOStreams {
-	fileIsTerminal := func(v any) bool {
-		if f, ok := v.(*os.File); ok {
-			return term.IsTerminal(int(f.Fd()))
-		}
-		return false
+	isTerminal := false
+	if f, ok := in.(*os.File); ok {
+		isTerminal = term.IsTerminal(int(f.Fd()))
 	}
-	return &IOStreams{
-		In:               in,
-		Out:              out,
-		ErrOut:           errOut,
-		IsTerminal:       fileIsTerminal(in),
-		OutIsTerminal:    fileIsTerminal(out),
-		StderrIsTerminal: fileIsTerminal(errOut),
+	stderrIsTerminal := false
+	if f, ok := errOut.(*os.File); ok {
+		stderrIsTerminal = term.IsTerminal(int(f.Fd()))
 	}
+	return &IOStreams{In: in, Out: out, ErrOut: errOut, IsTerminal: isTerminal, StderrIsTerminal: stderrIsTerminal}
+}
+
+// StdoutIsTerminal reports whether Out is an interactive terminal. Unlike
+// IsTerminal — which reflects stdin and drives prompt decisions — this is the
+// correct check for OUTPUT formatting: `cmd | jq` must still emit machine output
+// from an interactive shell (stdin is a TTY there, but stdout is the pipe).
+// Buffers (tests) and redirects are not *os.File terminals, so they yield false.
+func (s *IOStreams) StdoutIsTerminal() bool {
+	f, ok := s.Out.(*os.File)
+	return ok && term.IsTerminal(int(f.Fd()))
 }
 
 // SystemIO creates an IOStreams wired to the process's standard file descriptors.

internal/cmdutil/iostreams_test.go

@@ -9,23 +9,20 @@ import (
 	"testing"
 )
 
-func TestNewIOStreamsTerminalFlagsNonFile(t *testing.T) {
-	s := NewIOStreams(&bytes.Buffer{}, &bytes.Buffer{}, &bytes.Buffer{})
-	if s.IsTerminal || s.OutIsTerminal || s.StderrIsTerminal {
-		t.Errorf("non-file streams must not be terminals: in=%v out=%v err=%v",
-			s.IsTerminal, s.OutIsTerminal, s.StderrIsTerminal)
+func TestStdoutIsTerminal(t *testing.T) {
+	// Buffer-backed output (tests, captured output) is never a terminal.
+	if (&IOStreams{Out: &bytes.Buffer{}}).StdoutIsTerminal() {
+		t.Error("bytes.Buffer Out should not be a terminal")
 	}
-}
-
-func TestNewIOStreamsTerminalFlagsPipe(t *testing.T) {
+	// An os.Pipe write end is an *os.File but not a terminal — mirrors `cmd | jq`,
+	// the case the stdin-based IsTerminal would get wrong.
 	r, w, err := os.Pipe()
 	if err != nil {
 		t.Fatal(err)
 	}
 	defer r.Close()
 	defer w.Close()
-	s := NewIOStreams(r, w, w)
-	if s.OutIsTerminal || s.StderrIsTerminal {
-		t.Errorf("os.Pipe must not be a terminal: out=%v err=%v", s.OutIsTerminal, s.StderrIsTerminal)
+	if (&IOStreams{Out: w}).StdoutIsTerminal() {
+		t.Error("os.Pipe Out should not be a terminal")
 	}
 }

internal/core/config.go

@@ -36,6 +36,13 @@ type AppUser struct {
 	UserName   string `json:"userName"`
 }
 
+// Auth methods for app credentials. An empty AppConfig.AuthMethod means the
+// default, client_secret.
+const (
+	AuthMethodClientSecret  = "client_secret"   // app_id + app_secret
+	AuthMethodPrivateKeyJWT = "private_key_jwt" // TEE-signed client_assertion; no app secret
+)
+
 // AppConfig is a per-app configuration entry (stored format — secrets may be unresolved).
 type AppConfig struct {
 	Name       string      `json:"name,omitempty"`
@@ -46,6 +53,15 @@ type AppConfig struct {
 	DefaultAs  Identity    `json:"defaultAs,omitempty"` // AsUser | AsBot | AsAuto
 	StrictMode *StrictMode `json:"strictMode,omitempty"`
 	Users      []AppUser   `json:"users"`
+
+	// AuthMethod selects how tokens are minted. Empty == AuthMethodClientSecret
+	// (back-compat). AuthMethodPrivateKeyJWT uses a TEE-held key (see KeyRef) to
+	// sign client_assertion JWTs instead of sending an app secret.
+	AuthMethod string `json:"authMethod,omitempty"`
+	// KeyRef references the non-exportable signing key for private_key_jwt.
+	// Source is "tee" and ID is the backend key label; the actual key never
+	// leaves the secure backend, so this is a handle, not secret material.
+	KeyRef *SecretRef `json:"keyRef,omitempty"`
 }
 
 // ProfileName returns the display name for this app config.
@@ -161,7 +177,9 @@ type CliConfig struct {
 	UserOpenId          string
 	UserName            string
 	Lang                i18n.Lang
-	SupportedIdentities uint8 `json:"-"` // bitflag: 1=user, 2=bot; set by credential provider
+	SupportedIdentities uint8  `json:"-"` // bitflag: 1=user, 2=bot; set by credential provider
+	AuthMethod          string // "" == client_secret; AuthMethodPrivateKeyJWT
+	KeyLabel            string // resolved TEE key handle for private_key_jwt
 }
 
 // identityBotBit is the bit flag for bot identity in SupportedIdentities.
@@ -247,31 +265,58 @@ func ResolveConfigFromMulti(raw *MultiAppConfig, kc keychain.KeychainAccess, pro
 			WithHint("available profiles: %s", formatProfileNames(raw.ProfileNames()))
 	}
 
-	if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
-		return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "appId and appSecret keychain key are out of sync").
-			WithHint("%s", err.Error()).
-			WithCause(err)
+	// Validate the auth method first so a malformed profile fails here rather
+	// than silently degrading to client_secret (unknown method) or failing later
+	// at token-signing. Empty stays empty — downstream treats it as client_secret
+	// (back-compat).
+	switch app.AuthMethod {
+	case "", AuthMethodClientSecret, AuthMethodPrivateKeyJWT:
+	default:
+		return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "unknown authMethod %q", app.AuthMethod).
+			WithHint("supported: %s, %s (empty defaults to %s)", AuthMethodClientSecret, AuthMethodPrivateKeyJWT, AuthMethodClientSecret)
 	}
 
-	secret, err := ResolveSecretInput(app.AppSecret, kc)
-	if err != nil {
-		if errs.IsTyped(err) {
-			return nil, err
+	// private_key_jwt carries no secret: validate the key handle and skip secret
+	// resolution entirely, so a stale/broken AppSecret ref never produces a
+	// confusing secret-resolution error for an otherwise-valid pkjwt profile.
+	var secret string
+	if app.AuthMethod == AuthMethodPrivateKeyJWT {
+		if app.KeyRef == nil || app.KeyRef.Source != "tee" || app.KeyRef.ID == "" {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidConfig, "private_key_jwt requires a key handle (keyRef) but none is configured").
+				WithHint("re-run: lark-cli config init --new --auth-method private_key_jwt")
 		}
-		subtype := errs.SubtypeNotConfigured
-		if isMalformedConfigError(err) {
-			subtype = errs.SubtypeInvalidConfig
+	} else {
+		if err := ValidateSecretKeyMatch(app.AppId, app.AppSecret); err != nil {
+			return nil, errs.NewConfigError(errs.SubtypeNotConfigured, "appId and appSecret keychain key are out of sync").
+				WithHint("%s", err.Error()).
+				WithCause(err)
+		}
+		var resolveErr error
+		secret, resolveErr = ResolveSecretInput(app.AppSecret, kc)
+		if resolveErr != nil {
+			if errs.IsTyped(resolveErr) {
+				return nil, resolveErr
+			}
+			subtype := errs.SubtypeNotConfigured
+			if isMalformedConfigError(resolveErr) {
+				subtype = errs.SubtypeInvalidConfig
+			}
+			return nil, errs.NewConfigError(subtype, "%s", resolveErr.Error()).WithCause(resolveErr)
 		}
-		return nil, errs.NewConfigError(subtype, "%s", err.Error()).WithCause(err)
 	}
+
 	cfg := &CliConfig{
 		ProfileName: app.ProfileName(),
 		AppID:       app.AppId,
 		AppSecret:   secret,
 		Brand:       app.Brand,
 		Lang:        app.Lang,
+		AuthMethod:  app.AuthMethod,
 		DefaultAs:   app.DefaultAs,
 	}
+	if app.KeyRef != nil {
+		cfg.KeyLabel = app.KeyRef.ID
+	}
 	if len(app.Users) > 0 {
 		cfg.UserOpenId = app.Users[0].UserOpenId
 		cfg.UserName = app.Users[0].UserName

internal/core/config_test.go

@@ -133,6 +133,108 @@ func TestResolveConfigFromMulti_AcceptsPlainSecret(t *testing.T) {
 	}
 }
 
+// TestResolveConfigFromMulti_RejectsUnknownAuthMethod ensures an unsupported
+// authMethod fails at resolution rather than silently degrading to client_secret.
+func TestResolveConfigFromMulti_RejectsUnknownAuthMethod(t *testing.T) {
+	raw := &MultiAppConfig{
+		Apps: []AppConfig{
+			{
+				AppId:      "cli_abc",
+				AppSecret:  PlainSecret("my-secret"),
+				Brand:      BrandFeishu,
+				AuthMethod: "bogus_method",
+			},
+		},
+	}
+
+	_, err := ResolveConfigFromMulti(raw, nil, "")
+	if err == nil {
+		t.Fatal("expected error for unknown authMethod")
+	}
+	var cfgErr *errs.ConfigError
+	if !errors.As(err, &cfgErr) {
+		t.Fatalf("expected ConfigError, got %T: %v", err, err)
+	}
+}
+
+// TestResolveConfigFromMulti_PrivateKeyJWTRequiresKeyRef ensures private_key_jwt
+// without a key handle fails at resolution rather than later at token-signing.
+func TestResolveConfigFromMulti_PrivateKeyJWTRequiresKeyRef(t *testing.T) {
+	raw := &MultiAppConfig{
+		Apps: []AppConfig{
+			{
+				AppId:      "cli_abc",
+				AppSecret:  SecretInput{}, // private_key_jwt carries no app secret
+				Brand:      BrandFeishu,
+				AuthMethod: AuthMethodPrivateKeyJWT,
+				// KeyRef intentionally nil
+			},
+		},
+	}
+
+	_, err := ResolveConfigFromMulti(raw, nil, "")
+	if err == nil {
+		t.Fatal("expected error for private_key_jwt without keyRef")
+	}
+	var cfgErr *errs.ConfigError
+	if !errors.As(err, &cfgErr) {
+		t.Fatalf("expected ConfigError, got %T: %v", err, err)
+	}
+
+	// Control: same config WITH a keyRef resolves cleanly and sets KeyLabel.
+	raw.Apps[0].KeyRef = &SecretRef{Source: "tee", ID: "larksuite-cli-agent"}
+	cfg, err := ResolveConfigFromMulti(raw, nil, "")
+	if err != nil {
+		t.Fatalf("unexpected error with keyRef present: %v", err)
+	}
+	if cfg.KeyLabel != "larksuite-cli-agent" {
+		t.Errorf("KeyLabel = %q, want larksuite-cli-agent", cfg.KeyLabel)
+	}
+}
+
+// TestResolveConfigFromMulti_PKJWTSkipsSecretResolution ensures a private_key_jwt
+// profile that carries a stale/broken AppSecret ref still resolves cleanly: the
+// auth method is judged before any secret handling, so the stale ref is ignored
+// instead of producing a confusing secret-resolution failure.
+func TestResolveConfigFromMulti_PKJWTSkipsSecretResolution(t *testing.T) {
+	raw := &MultiAppConfig{
+		Apps: []AppConfig{{
+			AppId: "cli_pk",
+			// Stale keychain ref whose ID does not match appId — would trip
+			// ValidateSecretKeyMatch / ResolveSecretInput if it were reached.
+			AppSecret:  SecretInput{Ref: &SecretRef{Source: "keychain", ID: "appsecret:cli_OTHER"}},
+			Brand:      BrandFeishu,
+			AuthMethod: AuthMethodPrivateKeyJWT,
+			KeyRef:     &SecretRef{Source: "tee", ID: "agent-key"},
+			Users:      []AppUser{},
+		}},
+	}
+	cfg, err := ResolveConfigFromMulti(raw, stubKeychain{}, "")
+	if err != nil {
+		t.Fatalf("pkjwt with stale secret ref must skip secret resolution, got %v", err)
+	}
+	if cfg.AuthMethod != AuthMethodPrivateKeyJWT || cfg.KeyLabel != "agent-key" {
+		t.Errorf("got authMethod=%q keyLabel=%q", cfg.AuthMethod, cfg.KeyLabel)
+	}
+}
+
+// TestResolveConfigFromMulti_PKJWTRejectsBadKeyRef ensures the stricter keyRef
+// check (Source=="tee" && ID!="") rejects malformed handles.
+func TestResolveConfigFromMulti_PKJWTRejectsBadKeyRef(t *testing.T) {
+	for i, ref := range []*SecretRef{
+		{Source: "keychain", ID: "x"}, // wrong source
+		{Source: "tee", ID: ""},       // empty id
+	} {
+		raw := &MultiAppConfig{Apps: []AppConfig{{
+			AppId: "cli_pk", Brand: BrandFeishu,
+			AuthMethod: AuthMethodPrivateKeyJWT, KeyRef: ref, Users: []AppUser{},
+		}}}
+		if _, err := ResolveConfigFromMulti(raw, stubKeychain{}, ""); err == nil {
+			t.Errorf("case %d: expected ConfigError for bad keyRef", i)
+		}
+	}
+}
+
 func TestResolveConfigFromMulti_CarriesLang(t *testing.T) {
 	raw := &MultiAppConfig{
 		Apps: []AppConfig{

internal/core/types.go

@@ -3,6 +3,8 @@
 
 package core
 
+import "strings"
+
 // LarkBrand represents the Lark platform brand.
 // "feishu" targets China-mainland, "lark" targets international.
 // Any other string is treated as a custom base URL.
@@ -60,3 +62,10 @@ func ResolveEndpoints(brand LarkBrand) Endpoints {
 func ResolveOpenBaseURL(brand LarkBrand) string {
 	return ResolveEndpoints(brand).Open
 }
+
+// OpenAPIAudience returns the client_assertion `aud` value for the brand: the
+// bare Open API host per the App Authentication JWT spec — "open.feishu.cn" or
+// "open.larksuite.com" — not the full token endpoint URL.
+func OpenAPIAudience(brand LarkBrand) string {
+	return strings.TrimPrefix(ResolveOpenBaseURL(brand), "https://")
+}

internal/core/types_test.go

@@ -57,3 +57,12 @@ func TestResolveOpenBaseURL(t *testing.T) {
 		t.Errorf("ResolveOpenBaseURL(lark) = %q", got)
 	}
 }
+
+func TestOpenAPIAudience(t *testing.T) {
+	if got := OpenAPIAudience(BrandFeishu); got != "open.feishu.cn" {
+		t.Errorf("OpenAPIAudience(feishu) = %q, want open.feishu.cn", got)
+	}
+	if got := OpenAPIAudience(BrandLark); got != "open.larksuite.com" {
+		t.Errorf("OpenAPIAudience(lark) = %q, want open.larksuite.com", got)
+	}
+}

internal/credential/default_provider.go

@@ -17,6 +17,7 @@ import (
 	"github.com/larksuite/cli/internal/keychain"
 
 	extcred "github.com/larksuite/cli/extension/credential"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // classifyTATResponseCode wraps a deterministic (non-transient) failure from the
@@ -175,6 +176,23 @@ func (p *DefaultTokenProvider) doResolveTAT(ctx context.Context) (*TokenResult,
 	if err != nil {
 		return nil, err
 	}
+
+	// private_key_jwt apps have no app secret: mint via the jwt-bearer grant
+	// using a TEE-signed client_assertion instead.
+	if acct.AuthMethod == core.AuthMethodPrivateKeyJWT {
+		signer := keysigner.Active()
+		if signer == nil {
+			return nil, errs.NewConfigError(errs.SubtypeInvalidClient,
+				"profile uses private_key_jwt but no TEE key signer is available on this build").
+				WithHint("install a build with the platform key-signer extension, or reconfigure the app to use an app secret")
+		}
+		token, err := FetchTATWithAssertion(ctx, httpClient, acct.Brand, acct.AppID, signer, acct.KeyLabel)
+		if err != nil {
+			return nil, err
+		}
+		return &TokenResult{Token: token}, nil
+	}
+
 	token, err := FetchTAT(ctx, httpClient, acct.Brand, acct.AppID, acct.AppSecret)
 	if err != nil {
 		return nil, err

internal/credential/tat_fetch.go

@@ -11,8 +11,13 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+	"time"
 
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/auth/jwt"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // FetchTAT performs a single HTTP POST to mint a tenant access token via the
@@ -100,3 +105,96 @@ func FetchTAT(ctx context.Context, httpClient *http.Client, brand core.LarkBrand
 	}
 	return "", classifyTATResponseCode(result.Code, result.Error, desc, string(brand), appID)
 }
+
+// FetchTATWithAssertion mints a tenant access token for a private_key_jwt app via
+// the RFC 7523 jwt-bearer grant: it signs a short-lived client_assertion with the
+// TEE-held key and posts it to the unified OAuth token endpoint, replacing the
+// app_secret entirely.
+//
+// The unified v2 token endpoint returns the minted token as access_token
+// (tenant_access_token is accepted as a fallback).
+func FetchTATWithAssertion(ctx context.Context, httpClient *http.Client, brand core.LarkBrand, clientID string, signer keysigner.Signer, keyLabel string) (string, error) {
+	if signer == nil {
+		return "", fmt.Errorf("private_key_jwt requires a key signer, but none is available on this build")
+	}
+	ep := core.ResolveEndpoints(brand)
+	endpoint := ep.Open + auth.PathOAuthTokenV2
+
+	assertion, err := jwt.SignClientAssertion(ctx, signer, keysigner.KeyRef{Label: keyLabel}, clientID, core.OpenAPIAudience(brand), time.Now())
+	if err != nil {
+		return "", err
+	}
+
+	form := url.Values{}
+	form.Set("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer")
+	form.Set("client_id", clientID)
+	form.Set("client_assertion_type", jwt.ClientAssertionType)
+	form.Set("client_assertion", assertion)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, strings.NewReader(form.Encode()))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("read token response: %w", err)
+	}
+
+	var result struct {
+		Code              int    `json:"code"`
+		Msg               string `json:"msg"`
+		Error             string `json:"error"`
+		ErrorDescription  string `json:"error_description"`
+		AccessToken       string `json:"access_token"`
+		TenantAccessToken string `json:"tenant_access_token"`
+	}
+	_ = json.Unmarshal(body, &result) // best-effort; error body may not be JSON
+
+	token := result.AccessToken
+	if token == "" {
+		token = result.TenantAccessToken
+	}
+	if resp.StatusCode == http.StatusOK && token != "" && result.Error == "" && result.Code == 0 {
+		return token, nil
+	}
+
+	// Surface the server's reason, preferring the OAuth `error` code (e.g.
+	// unauthorized_client) which is more diagnostic than the description alone.
+	detail := result.ErrorDescription
+	if detail == "" {
+		detail = result.Msg
+	}
+	if detail == "" {
+		detail = strings.TrimSpace(string(body))
+	}
+	if result.Error != "" {
+		return "", classifyAssertionError(result.Error, resp.StatusCode, detail)
+	}
+	return "", fmt.Errorf("token endpoint HTTP %d (code=%d): %s", resp.StatusCode, result.Code, detail)
+}
+
+// classifyAssertionError maps the OAuth token endpoint's `error` field to a
+// typed or untyped error. Only deterministic client-credential rejections get a
+// typed errs.ConfigError (so runProbePKJWT can tell "this key is not bound to
+// this app" apart from upstream noise); every other error (e.g.
+// temporarily_unavailable) stays untyped and is swallowed by the probe. detail
+// carries only the server's error_description / msg / body text — it never
+// echoes the client_assertion or private key (the assertion lives only in the
+// request form).
+func classifyAssertionError(oauthError string, httpStatus int, detail string) error {
+	switch oauthError {
+	case "invalid_client", "unauthorized_client", "invalid_grant":
+		return errs.NewConfigError(errs.SubtypeInvalidClient,
+			"token endpoint rejected the key (%s): %s", oauthError, detail)
+	default:
+		return fmt.Errorf("token endpoint HTTP %d (%s): %s", httpStatus, oauthError, detail)
+	}
+}

internal/credential/tat_fetch_test.go

@@ -5,15 +5,24 @@ package credential
 
 import (
 	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"encoding/json"
 	"errors"
 	"io"
 	"net/http"
 	"net/http/httptest"
+	"net/url"
 	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/keysigner"
 )
 
 // stubRoundTripper lets us assert request shape and return canned responses.
@@ -307,3 +316,147 @@ func (r *urlRewriteRT) RoundTrip(req *http.Request) (*http.Response, error) {
 	req2.Header = req.Header
 	return http.DefaultTransport.RoundTrip(req2)
 }
+
+// fakeTATSigner is a real in-memory ECDSA P-256 signer for assertion tests.
+type fakeTATSigner struct{ key *ecdsa.PrivateKey }
+
+func newFakeTATSigner(t *testing.T) *fakeTATSigner {
+	t.Helper()
+	k, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return &fakeTATSigner{key: k}
+}
+
+func (f *fakeTATSigner) EnsureKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeTATSigner) PublicKey(context.Context, keysigner.KeyRef) (crypto.PublicKey, error) {
+	return f.key.Public(), nil
+}
+func (f *fakeTATSigner) Sign(_ context.Context, _ keysigner.KeyRef, in []byte) ([]byte, string, error) {
+	h := sha256.Sum256(in)
+	r, s, err := ecdsa.Sign(rand.Reader, f.key, h[:])
+	if err != nil {
+		return nil, "", err
+	}
+	sig := make([]byte, 64)
+	r.FillBytes(sig[:32])
+	s.FillBytes(sig[32:])
+	return sig, keysigner.AlgES256, nil
+}
+
+func TestFetchTATWithAssertion_Success(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"access_token":"t-jwt","token_type":"Bearer","expires_in":7200}`}
+	hc := &http.Client{Transport: rt}
+
+	token, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "agent-key")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if token != "t-jwt" {
+		t.Errorf("token = %q, want t-jwt", token)
+	}
+	if rt.gotReq.URL.String() != "https://open.feishu.cn/open-apis/authen/v2/oauth/token" {
+		t.Errorf("url = %s", rt.gotReq.URL.String())
+	}
+
+	form, err := url.ParseQuery(rt.gotBody)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if form.Get("grant_type") != "urn:ietf:params:oauth:grant-type:jwt-bearer" {
+		t.Errorf("grant_type = %q", form.Get("grant_type"))
+	}
+	if form.Get("client_assertion_type") != "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" {
+		t.Errorf("client_assertion_type = %q", form.Get("client_assertion_type"))
+	}
+	if form.Get("client_assertion") == "" {
+		t.Error("client_assertion is empty")
+	}
+	if form.Has("client_secret") {
+		t.Error("client_secret must NOT be sent for private_key_jwt")
+	}
+
+	// The assertion's aud must be the bare Open host per the App Authentication
+	// JWT spec — not the full token endpoint URL.
+	jwtParts := strings.Split(form.Get("client_assertion"), ".")
+	if len(jwtParts) != 3 {
+		t.Fatalf("malformed client_assertion: %q", form.Get("client_assertion"))
+	}
+	payload, err := base64.RawURLEncoding.DecodeString(jwtParts[1])
+	if err != nil {
+		t.Fatalf("assertion payload not base64url: %v", err)
+	}
+	var claims map[string]any
+	if err := json.Unmarshal(payload, &claims); err != nil {
+		t.Fatal(err)
+	}
+	if claims["aud"] != "open.feishu.cn" {
+		t.Errorf("client_assertion aud = %v, want open.feishu.cn", claims["aud"])
+	}
+	if claims["iss"] != "cli_app" || claims["sub"] != "cli_app" {
+		t.Errorf("client_assertion iss/sub = %v/%v, want cli_app", claims["iss"], claims["sub"])
+	}
+	if form.Get("client_id") != "cli_app" {
+		t.Errorf("client_id = %q", form.Get("client_id"))
+	}
+}
+
+func TestFetchTATWithAssertion_NilSigner(t *testing.T) {
+	hc := &http.Client{Transport: &stubRoundTripper{respCode: 200, respBody: `{}`}}
+	if _, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", nil, "k"); err == nil {
+		t.Fatal("expected error when signer is nil")
+	}
+}
+
+func TestFetchTATWithAssertion_ServerError(t *testing.T) {
+	rt := &stubRoundTripper{respCode: 200, respBody: `{"error":"invalid_client","error_description":"unknown key"}`}
+	hc := &http.Client{Transport: rt}
+	if _, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k"); err == nil {
+		t.Fatal("expected error for invalid_client response")
+	}
+}
+
+// Deterministic OAuth client rejections must be typed (ConfigError /
+// SubtypeInvalidClient) so runProbePKJWT can tell "the key is not bound to this
+// app" apart from transport noise.
+func TestFetchTATWithAssertion_DeterministicReject_Typed(t *testing.T) {
+	for _, oauthErr := range []string{"invalid_client", "unauthorized_client", "invalid_grant"} {
+		rt := &stubRoundTripper{respCode: 401, respBody: `{"error":"` + oauthErr + `","error_description":"bad key"}`}
+		hc := &http.Client{Transport: rt}
+		_, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k")
+		if err == nil {
+			t.Fatalf("%s: expected error", oauthErr)
+		}
+		if !errs.IsTyped(err) {
+			t.Errorf("%s: must be typed, got %T", oauthErr, err)
+		}
+		var cfgErr *errs.ConfigError
+		if !errors.As(err, &cfgErr) || cfgErr.Subtype != errs.SubtypeInvalidClient {
+			t.Errorf("%s: want ConfigError/InvalidClient, got %T %v", oauthErr, err, err)
+		}
+	}
+}
+
+// Unrecognized OAuth errors and non-payload noise stay UNTYPED so the probe
+// treats them as upstream noise and stays silent.
+func TestFetchTATWithAssertion_AmbiguousError_Untyped(t *testing.T) {
+	cases := []string{
+		`{"error":"temporarily_unavailable","error_description":"retry"}`,
+		`{"code":99999,"msg":"weird"}`,
+		`not json`,
+	}
+	for _, body := range cases {
+		rt := &stubRoundTripper{respCode: 503, respBody: body}
+		hc := &http.Client{Transport: rt}
+		_, err := FetchTATWithAssertion(context.Background(), hc, core.BrandFeishu, "cli_app", newFakeTATSigner(t), "k")
+		if err == nil {
+			t.Fatalf("body %q: expected error", body)
+		}
+		if errs.IsTyped(err) {
+			t.Errorf("body %q: must be UNTYPED, got typed %T", body, err)
+		}
+	}
+}

internal/credential/types.go

@@ -26,6 +26,8 @@ type Account struct {
 	UserName            string
 	Lang                i18n.Lang
 	SupportedIdentities uint8
+	AuthMethod          string // "" == client_secret; core.AuthMethodPrivateKeyJWT
+	KeyLabel            string // resolved TEE key handle for private_key_jwt
 }
 
 const runtimePlaceholderAppSecret = "__LARKSUITE_CLI_TOKEN_ONLY__"
@@ -69,6 +71,8 @@ func AccountFromCliConfig(cfg *core.CliConfig) *Account {
 		UserName:            cfg.UserName,
 		Lang:                cfg.Lang,
 		SupportedIdentities: cfg.SupportedIdentities,
+		AuthMethod:          cfg.AuthMethod,
+		KeyLabel:            cfg.KeyLabel,
 	}
 }
 
@@ -87,6 +91,8 @@ func (a *Account) ToCliConfig() *core.CliConfig {
 		UserName:            a.UserName,
 		Lang:                a.Lang,
 		SupportedIdentities: a.SupportedIdentities,
+		AuthMethod:          a.AuthMethod,
+		KeyLabel:            a.KeyLabel,
 	}
 }
 

internal/errclass/classify.go

@@ -10,14 +10,12 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
 )
 
 // ClassifyContext is the contextual data BuildAPIError uses to populate
 // identity-aware fields on typed errors (PermissionError.Identity / ConsoleURL).
-// Brand and Identity are plain strings at this boundary; ConsoleURL normalizes
-// Brand through core.ParseBrand, so callers can pass a raw brand string without
-// coupling this contract to core's brand enum.
+// Identity is a plain string ("user" / "bot" / "") so this package does not
+// depend on internal/core (which would create an import cycle).
 type ClassifyContext struct {
 	Brand    string // "feishu" | "lark" — drives console_url host
 	AppID    string // placed in console_url
@@ -446,27 +444,28 @@ func extractMissingScopes(resp map[string]any) []string {
 	return out
 }
 
-// ConsoleURL composes the Feishu/Lark open-platform application-scope apply
-// page URL (the official open-pages `/page/scope-apply` entry), suitable for
-// PermissionError.ConsoleURL. Empty appID → empty string. Empty scopes list
-// returns the page carrying only clientID; otherwise scopes are joined with
-// commas in the `scopes` query parameter so the console can pre-select them.
+// ConsoleURL composes the Feishu/Lark open-platform scope-grant console URL,
+// suitable for PermissionError.ConsoleURL. Empty appID → empty string. Empty
+// scopes list returns the bare /auth landing page; scopes are joined with
+// commas in the `q` query parameter so the console can pre-select them.
 //
 // brand is "feishu" or "lark"; unknown values default to feishu.
 func ConsoleURL(brand, appID string, scopes []string) string {
 	if appID == "" {
 		return ""
 	}
-	// QueryEscape both values — clientID and scopes both sit in the query
-	// string, and untrusted content must not be able to inject extra query
-	// parameters via `&`/`#`. The brand→host mapping is owned by core so the
-	// open-platform base URL stays a single source of truth.
-	base := fmt.Sprintf("%s/page/scope-apply?clientID=%s",
-		core.ResolveOpenBaseURL(core.ParseBrand(brand)), url.QueryEscape(appID))
-	if len(scopes) == 0 {
-		return base
+	host := "open.feishu.cn"
+	if brand == "lark" {
+		host = "open.larksuite.com"
 	}
-	return base + "&scopes=" + url.QueryEscape(strings.Join(scopes, ","))
+	// PathEscape on appID — it sits in the URL path. QueryEscape on the
+	// comma-joined scopes — they sit in the `?q=` value, and untrusted scope
+	// content must not be able to inject extra query parameters via `&`/`#`.
+	pathID := url.PathEscape(appID)
+	if len(scopes) == 0 {
+		return fmt.Sprintf("https://%s/app/%s/auth", host, pathID)
+	}
+	return fmt.Sprintf("https://%s/app/%s/auth?q=%s", host, pathID, url.QueryEscape(strings.Join(scopes, ",")))
 }
 
 func intFromAny(v any) int {

internal/errclass/classify_test.go

@@ -422,8 +422,8 @@ func TestConsoleURL_FeishuBrand(t *testing.T) {
 	if !ok {
 		t.Fatalf("expected *errs.PermissionError, got %T", err)
 	}
-	if !strings.Contains(pe.ConsoleURL, "open.feishu.cn/page/scope-apply?clientID=cli_a123") {
-		t.Fatalf("ConsoleURL = %q, want open.feishu.cn scope-apply page", pe.ConsoleURL)
+	if !strings.Contains(pe.ConsoleURL, "open.feishu.cn/app/cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.feishu.cn prefix", pe.ConsoleURL)
 	}
 }
 
@@ -434,8 +434,8 @@ func TestConsoleURL_LarkBrand(t *testing.T) {
 	if !ok {
 		t.Fatalf("expected *errs.PermissionError, got %T", err)
 	}
-	if !strings.Contains(pe.ConsoleURL, "open.larksuite.com/page/scope-apply?clientID=cli_a123") {
-		t.Fatalf("ConsoleURL = %q, want open.larksuite.com scope-apply page", pe.ConsoleURL)
+	if !strings.Contains(pe.ConsoleURL, "open.larksuite.com/app/cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.larksuite.com prefix", pe.ConsoleURL)
 	}
 }
 
@@ -485,35 +485,35 @@ func TestConsoleURL_EscapesDangerousChars(t *testing.T) {
 			name:      "ampersand in scope smuggles extra param",
 			appID:     "cli_good",
 			scopes:    []string{"scope&evil=injected"},
-			wantInURL: []string{"scopes=scope%26evil%3Dinjected"},
-			denyInURL: []string{"scopes=scope&evil=injected"},
+			wantInURL: []string{"q=scope%26evil%3Dinjected"},
+			denyInURL: []string{"q=scope&evil=injected"},
 		},
 		{
 			name:      "hash in scope splits fragment",
 			appID:     "cli_good",
 			scopes:    []string{"scope#fragment"},
-			wantInURL: []string{"scopes=scope%23fragment"},
-			denyInURL: []string{"scopes=scope#fragment"},
+			wantInURL: []string{"q=scope%23fragment"},
+			denyInURL: []string{"q=scope#fragment"},
 		},
 		{
 			name:      "question mark in appID prematurely opens query",
 			appID:     "good?q=injected",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"clientID=good%3Fq%3Dinjected"},
-			denyInURL: []string{"clientID=good?q=injected"},
+			wantInURL: []string{"/app/good%3Fq=injected/auth"},
+			denyInURL: []string{"/app/good?q=injected/auth"},
 		},
 		{
 			name:      "hash in appID truncates URL",
 			appID:     "good#fragment",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"clientID=good%23fragment"},
-			denyInURL: []string{"clientID=good#fragment"},
+			wantInURL: []string{"/app/good%23fragment/auth"},
+			denyInURL: []string{"/app/good#fragment/auth"},
 		},
 		{
-			name:      "slash in appID does not open a new path segment",
+			name:      "slash in appID escapes path segment",
 			appID:     "good/extra/segment",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"clientID=good%2Fextra%2Fsegment"},
+			wantInURL: []string{"/app/good%2Fextra%2Fsegment/auth"},
 		},
 	}
 
@@ -553,8 +553,8 @@ func TestPermissionError_NoViolations(t *testing.T) {
 	if pe.MissingScopes != nil {
 		t.Errorf("MissingScopes should be nil; got %v", pe.MissingScopes)
 	}
-	if !strings.HasSuffix(pe.ConsoleURL, "/page/scope-apply?clientID=cli_a123") {
-		t.Errorf("ConsoleURL (no scopes) = %q, want trailing /page/scope-apply?clientID=cli_a123", pe.ConsoleURL)
+	if !strings.HasSuffix(pe.ConsoleURL, "/app/cli_a123/auth") {
+		t.Errorf("ConsoleURL (no scopes) = %q, want trailing /app/cli_a123/auth", pe.ConsoleURL)
 	}
 }
 
@@ -758,7 +758,7 @@ func TestBuildPermissionHint_AppMissingScopeRoutesToConsole(t *testing.T) {
 	// at the app level — re-authenticating cannot fix it. The hint must
 	// point to the developer console regardless of caller identity, or
 	// agents will loop on `auth login` forever.
-	consoleURL := "https://open.feishu.cn/page/scope-apply?clientID=cli_x&scopes=contact%3Acontact"
+	consoleURL := "https://open.feishu.cn/app/cli_x/auth?q=contact%3Acontact"
 	for _, identity := range []string{"user", "bot", ""} {
 		got := errclass.PermissionHint([]string{"contact:contact"}, identity, errs.SubtypeAppScopeNotApplied, consoleURL)
 		if !strings.Contains(got, "developer console") {

internal/errclass/codemeta_drive.go

@@ -10,20 +10,8 @@ import "github.com/larksuite/cli/errs"
 // ambiguous codes fall back to CategoryAPI via BuildAPIError.
 // BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
 var driveCodeMeta = map[int]CodeMeta{
-	1061001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
-	1061002:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
-	1061004:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
-	1061007:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
-	1061043:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
-	1061044:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
-	1062009:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
-	1063001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
-	1063002:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
-	1063013:  {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
-	1069302:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
-	99992402: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
-	9499:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
-	2200:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
+	1061044: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},          // parent folder does not exist (upload)
+	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // comment endpoint "Invalid or missing parameters"
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_drive_test.go

@@ -27,13 +27,6 @@ func TestLookupCodeMeta_DriveCodes(t *testing.T) {
 		// 1069302: comment endpoint's opaque "Invalid or missing parameters"
 		// (shortcuts/drive/drive_add_comment.go) → API-side parameter rejection.
 		{1069302, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		// Secure label endpoint codes observed from drive +secure-label-update
-		// failure telemetry.
-		{1063001, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{1063002, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
-		{1063013, errs.CategoryValidation, errs.SubtypeFailedPrecondition, false},
-		{99992402, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{9499, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {

internal/errclass/codemeta_test.go

@@ -102,35 +102,6 @@ func TestLookupCodeMeta_RetryableRateLimit(t *testing.T) {
 	}
 }
 
-func TestLookupCodeMeta_DrivePushCodes(t *testing.T) {
-	cases := []struct {
-		code        int
-		wantCat     errs.Category
-		wantSubtype errs.Subtype
-		wantRetry   bool
-	}{
-		{1061001, errs.CategoryAPI, errs.SubtypeServerError, true},
-		{1061002, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{1061004, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
-		{1061007, errs.CategoryAPI, errs.SubtypeNotFound, false},
-		{1061043, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
-		{1062009, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
-		{2200, errs.CategoryAPI, errs.SubtypeServerError, true},
-	}
-	for _, tc := range cases {
-		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
-			got, ok := LookupCodeMeta(tc.code)
-			if !ok {
-				t.Fatalf("LookupCodeMeta(%d) ok=false, want true", tc.code)
-			}
-			if got.Category != tc.wantCat || got.Subtype != tc.wantSubtype || got.Retryable != tc.wantRetry {
-				t.Fatalf("LookupCodeMeta(%d) = %+v, want Category=%v Subtype=%v Retryable=%v",
-					tc.code, got, tc.wantCat, tc.wantSubtype, tc.wantRetry)
-			}
-		})
-	}
-}
-
 func TestLookupCodeMeta_Unknown(t *testing.T) {
 	_, ok := LookupCodeMeta(999999)
 	if ok {

internal/identitydiag/diagnostics.go

@@ -13,7 +13,6 @@ import (
 	"strings"
 	"time"
 
-	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"
@@ -62,131 +61,12 @@ func Diagnose(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, veri
 	if ctx == nil {
 		ctx = context.Background()
 	}
-	// An external provider mints tokens on demand and blocks interactive auth,
-	// so the built-in keychain heuristics and "auth login" hints don't apply.
-	if provider := activeExternalProvider(ctx, f); provider != "" {
-		return diagnoseExternal(ctx, f, cfg, provider, verify)
-	}
 	return Result{
 		Bot:  diagnoseBot(ctx, f, cfg, verify),
 		User: diagnoseUser(ctx, f, cfg, verify),
 	}
 }
 
-// activeExternalProvider returns the active extension provider name, or "".
-// An error degrades to the built-in path: an unreachable provider would already
-// have failed the f.Config() that produced cfg.
-func activeExternalProvider(ctx context.Context, f *cmdutil.Factory) string {
-	if f == nil || f.Credential == nil {
-		return ""
-	}
-	name, err := f.Credential.ActiveExtensionProviderName(ctx)
-	if err != nil {
-		return ""
-	}
-	return name
-}
-
-func diagnoseExternal(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, verify bool) Result {
-	if cfg == nil || cfg.AppID == "" {
-		notConfigured := Identity{
-			Status:  StatusNotConfigured,
-			Message: "not configured (missing app config)",
-			Hint:    externalCredentialHint(provider),
-		}
-		return Result{Bot: notConfigured, User: notConfigured}
-	}
-	// SupportedIdentities == 0 is "unspecified" — treat as both, per CanBot.
-	ids := extcred.IdentitySupport(cfg.SupportedIdentities)
-	supportsBot := cfg.SupportedIdentities == 0 || ids.Has(extcred.SupportsBot)
-	supportsUser := cfg.SupportedIdentities == 0 || ids.Has(extcred.SupportsUser)
-	return Result{
-		Bot:  diagnoseExternalBot(ctx, f, cfg, provider, supportsBot, verify),
-		User: diagnoseExternalUser(ctx, f, cfg, provider, supportsUser, verify),
-	}
-}
-
-func diagnoseExternalBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, supported, verify bool) Identity {
-	if !supported {
-		return notProvidedExternally("Bot", provider)
-	}
-	id := Identity{Status: StatusReady, Available: true, Message: "Bot identity: ready (provided by " + provider + ")"}
-	if !verify {
-		return id
-	}
-	token, err := resolveBotToken(ctx, f, cfg)
-	if err != nil {
-		return externalVerifyFailed(id, "Bot", provider, err)
-	}
-	info, err := fetchBotInfo(ctx, f, cfg, token)
-	if err != nil {
-		return externalVerifyFailed(id, "Bot", provider, err)
-	}
-	id.Verified = boolPtr(true)
-	id.OpenID = info.OpenID
-	id.AppName = info.AppName
-	return id
-}
-
-func diagnoseExternalUser(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, provider string, supported, verify bool) Identity {
-	if !supported {
-		return notProvidedExternally("User", provider)
-	}
-	// enrichUserInfo populates UserOpenId only after the provider returns and
-	// verifies a UAT (and clears it on failure), so a resolved open id is the
-	// external analogue of a keychain token being present.
-	if cfg.UserOpenId == "" {
-		return Identity{
-			Status:  StatusMissing,
-			Message: "User identity: not signed in via credential source " + provider,
-			Hint:    externalCredentialHint(provider),
-		}
-	}
-	id := Identity{
-		Status:      StatusReady,
-		Available:   true,
-		TokenStatus: StatusReady,
-		UserName:    cfg.UserName,
-		OpenID:      cfg.UserOpenId,
-		Message:     "User identity: ready (provided by " + provider + ")",
-	}
-	if !verify {
-		return id
-	}
-	if _, err := f.Credential.ResolveToken(ctx, credential.NewTokenSpec(core.AsUser, cfg.AppID)); err != nil {
-		return externalVerifyFailed(id, "User", provider, err)
-	}
-	id.Verified = boolPtr(true)
-	return id
-}
-
-func notProvidedExternally(label, provider string) Identity {
-	return Identity{
-		Status:  StatusNotConfigured,
-		Message: label + " identity: not provided by credential source " + provider,
-		Hint:    externalCredentialHint(provider),
-	}
-}
-
-// externalVerifyFailed flips id to verify-failed, keeping any identity fields
-// (open id, user name) already resolved before the probe.
-func externalVerifyFailed(id Identity, label, provider string, err error) Identity {
-	id.Available = false
-	id.Verified = boolPtr(false)
-	id.Status = StatusVerifyFailed
-	id.TokenStatus = ""
-	id.Message = label + " identity: verify failed: " + err.Error()
-	id.Hint = externalCredentialHint(provider)
-	return id
-}
-
-// externalCredentialHint reports the constraint, not a remediation: the
-// identity is the provider's to manage, not lark-cli's to fix. What to do about
-// it is the caller's call — there may be no user to ask.
-func externalCredentialHint(provider string) string {
-	return fmt.Sprintf("managed by the external credential provider %q and cannot be configured via lark-cli", provider)
-}
-
 func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, verify bool) Identity {
 	if cfg == nil || cfg.AppID == "" {
 		return Identity{
@@ -202,7 +82,9 @@ func diagnoseBot(ctx context.Context, f *cmdutil.Factory, cfg *core.CliConfig, v
 			Hint:    "check strict mode or the active credential provider",
 		}
 	}
-	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) {
+	// private_key_jwt apps have no app secret — the bot/tenant token is minted via
+	// a TEE-signed client_assertion — so absence of a secret is NOT "unconfigured".
+	if cfg.SupportedIdentities == 0 && !credential.HasRealAppSecret(cfg.AppSecret) && cfg.AuthMethod != core.AuthMethodPrivateKeyJWT {
 		return Identity{
 			Status:  StatusNotConfigured,
 			Message: "Bot identity: not configured (missing app secret or bot token)",

internal/identitydiag/diagnostics_test.go

@@ -10,11 +10,9 @@ import (
 	"testing"
 	"time"
 
-	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/httpmock"
 	"github.com/zalando/go-keyring"
 )
@@ -350,136 +348,3 @@ func TestDiagnose_UserIdentityNeedsRefresh(t *testing.T) {
 		t.Fatalf("token status = %q, want needs_refresh", got.User.TokenStatus)
 	}
 }
-
-// fakeExtProvider is a minimal credential.extcred.Provider for exercising the
-// external-credential diagnosis path. account makes the provider "active";
-// token (when set) satisfies ResolveToken during verify.
-type fakeExtProvider struct {
-	name    string
-	account *extcred.Account
-	token   *extcred.Token
-}
-
-func (p *fakeExtProvider) Name() string { return p.name }
-func (p *fakeExtProvider) ResolveAccount(context.Context) (*extcred.Account, error) {
-	return p.account, nil
-}
-func (p *fakeExtProvider) ResolveToken(context.Context, extcred.TokenSpec) (*extcred.Token, error) {
-	return p.token, nil
-}
-
-func externalFactory(prov *fakeExtProvider, cfg *core.CliConfig) *cmdutil.Factory {
-	cred := credential.NewCredentialProvider(
-		[]extcred.Provider{prov}, nil, nil,
-		func() (*http.Client, error) { return nil, nil },
-	)
-	return &cmdutil.Factory{
-		Config:     func() (*core.CliConfig, error) { return cfg, nil },
-		Credential: cred,
-		IOStreams:  &cmdutil.IOStreams{},
-	}
-}
-
-// assertExternalHint locks the contract that an external-provider hint never
-// points at interactive commands blocked under an external provider.
-func assertExternalHint(t *testing.T, hint string) {
-	t.Helper()
-	if hint == "" {
-		t.Fatalf("hint empty, want external guidance")
-	}
-	for _, blocked := range []string{"auth login", "config --help"} {
-		if strings.Contains(hint, blocked) {
-			t.Fatalf("hint %q must not point at %q (blocked under external provider)", hint, blocked)
-		}
-	}
-	if !strings.Contains(hint, "external") {
-		t.Fatalf("hint %q should explain credentials are external", hint)
-	}
-}
-
-func TestDiagnose_External_UserReady(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsAll), UserOpenId: "ou_x", UserName: "Alice"}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	// The bug this guards: the built-in path read the keychain (empty under an
-	// external provider) and reported the user as missing. Now availability
-	// follows the resolved account, so a signed-in user reads as ready.
-	if !got.User.Available || got.User.Status != StatusReady || got.User.TokenStatus != StatusReady {
-		t.Fatalf("user = %#v, want ready/available", got.User)
-	}
-	if got.User.OpenID != "ou_x" || got.User.UserName != "Alice" {
-		t.Fatalf("user identity = %#v", got.User)
-	}
-	if got.User.Hint != "" {
-		t.Fatalf("hint = %q, want empty when available", got.User.Hint)
-	}
-	if !got.Bot.Available || got.Bot.Status != StatusReady {
-		t.Fatalf("bot = %#v, want ready/available", got.Bot)
-	}
-}
-
-func TestDiagnose_External_UserNotSignedIn(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsAll)}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if got.User.Available || got.User.Status != StatusMissing {
-		t.Fatalf("user = %#v, want missing/unavailable", got.User)
-	}
-	assertExternalHint(t, got.User.Hint)
-}
-
-func TestDiagnose_External_BotOnly(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsBot), UserOpenId: "ou_x"}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if !got.Bot.Available || got.Bot.Status != StatusReady {
-		t.Fatalf("bot = %#v, want ready/available", got.Bot)
-	}
-	// Provider declares bot-only: user is unavailable even though an open id is
-	// present, and the hint is external (not "auth login").
-	if got.User.Available || got.User.Status != StatusNotConfigured {
-		t.Fatalf("user = %#v, want not_configured/unavailable", got.User)
-	}
-	assertExternalHint(t, got.User.Hint)
-}
-
-func TestDiagnose_External_UserOnly(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandLark, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x", UserName: "Bob"}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, false)
-	if !got.User.Available || got.User.Status != StatusReady {
-		t.Fatalf("user = %#v, want ready/available", got.User)
-	}
-	if got.Bot.Available || got.Bot.Status != StatusNotConfigured {
-		t.Fatalf("bot = %#v, want not_configured/unavailable", got.Bot)
-	}
-	assertExternalHint(t, got.Bot.Hint)
-}
-
-func TestDiagnose_External_VerifyUserResolvesToken(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x", UserName: "Alice"}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}, token: &extcred.Token{Value: "ext-uat"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if !got.User.Available || got.User.Verified == nil || !*got.User.Verified {
-		t.Fatalf("user = %#v, want available and verified", got.User)
-	}
-}
-
-func TestDiagnose_External_VerifyUserTokenUnavailable(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", Brand: core.BrandFeishu, SupportedIdentities: uint8(extcred.SupportsUser), UserOpenId: "ou_x"}
-	f := externalFactory(&fakeExtProvider{name: "corp-sso", account: &extcred.Account{AppID: "cli_x"}}, cfg)
-
-	got := Diagnose(context.Background(), f, cfg, true)
-	if got.User.Available || got.User.Status != StatusVerifyFailed {
-		t.Fatalf("user = %#v, want verify_failed/unavailable", got.User)
-	}
-	if got.User.Verified == nil || *got.User.Verified {
-		t.Fatalf("verified = %v, want false", got.User.Verified)
-	}
-	assertExternalHint(t, got.User.Hint)
-}

internal/keysigner/keysigner.go

@@ -0,0 +1,212 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package keysigner defines the pluggable signing abstraction used by the
+// private_key_jwt registration and authentication flow.
+//
+// The open-source core only declares the Signer interface and pure-stdlib key
+// helpers. The platform implementations that hold a non-exportable private key
+// (TPM 2.0 via facebookincubator/sks on Linux/Windows, a non-extractable
+// Keychain key on macOS) live OUTSIDE this core — in a build-tagged module or
+// extension — and register themselves via Register from init(). This keeps
+// CGO-heavy and license-sensitive dependencies out of the open-source build.
+package keysigner
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/asn1"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"math/big"
+	"strings"
+)
+
+// KeyRef identifies a non-exportable signing key held by a backend
+// (TEE/TPM/Keychain). It is a stable handle (label), never the key material.
+type KeyRef struct {
+	// Label is the backend key label/tag (e.g. "larksuite-cli-agent").
+	Label string
+}
+
+// Signer signs JWS signing inputs with a non-exportable key.
+type Signer interface {
+	// EnsureKey returns the public key for ref, creating the key if absent.
+	EnsureKey(ctx context.Context, ref KeyRef) (crypto.PublicKey, error)
+	// PublicKey returns the public key for ref without creating it.
+	PublicKey(ctx context.Context, ref KeyRef) (crypto.PublicKey, error)
+	// Sign signs signingInput and returns a JOSE-format signature plus the JWS
+	// alg ("ES256"/"RS256"). Implementations apply the alg's hash and, for
+	// ECDSA, MUST return the fixed-width r||s form required by RFC 7518 §3.4
+	// (not ASN.1 DER), because the backend (TPM/Keychain) typically yields DER.
+	Sign(ctx context.Context, ref KeyRef, signingInput []byte) (sig []byte, alg string, err error)
+}
+
+// Supported JWS algorithms.
+const (
+	AlgES256 = "ES256"
+	AlgRS256 = "RS256"
+)
+
+// DefaultKeyLabel is the backend key label lark-cli uses for its device signing
+// key. One non-exportable key is created on first private_key_jwt registration
+// and reused across subsequent app registrations on the same device.
+const DefaultKeyLabel = "larksuite-cli-agent"
+
+// HardwareInfo describes the secure hardware backing a Signer, as reported by a
+// HardwareProber. It is advisory/diagnostic: it tells a user whether
+// private_key_jwt can use a real TEE on this device.
+type HardwareInfo struct {
+	Backend    string // backing technology, e.g. "tpm2" or "keychain"
+	Available  bool   // the hardware is present and usable for signing
+	VendorName string // hardware vendor/manufacturer, when known
+	VendorInfo string // additional vendor detail, when known
+	Reason     string // when Available is false, a human-readable cause
+}
+
+// HardwareProber is an optional capability a Signer may implement to report on
+// the secure hardware backing it (TPM/TEE vendor and availability) WITHOUT
+// creating or using a key. Probing never mutates key state.
+type HardwareProber interface {
+	ProbeHardware(ctx context.Context) (HardwareInfo, error)
+}
+
+// ProbeActiveHardware probes the active signer's secure hardware. ok is false
+// when there is no active signer or it does not implement HardwareProber — in
+// which case private_key_jwt is unsupported on this build. When ok is true, info
+// reports availability and, if unavailable, info.Reason explains why.
+func ProbeActiveHardware(ctx context.Context) (info HardwareInfo, ok bool, err error) {
+	return probeHardware(ctx, Active())
+}
+
+// probeHardware is the registry-independent core of ProbeActiveHardware, so it
+// can be unit-tested without touching the global signer.
+func probeHardware(ctx context.Context, s Signer) (HardwareInfo, bool, error) {
+	p, ok := s.(HardwareProber)
+	if !ok {
+		return HardwareInfo{}, false, nil
+	}
+	info, err := p.ProbeHardware(ctx)
+	return info, true, err
+}
+
+// cleanProbeError renders err's message with redundant re-wraps collapsed. Some
+// backends (e.g. facebookincubator/sks) wrap an error twice with the SAME "%w"
+// prefix, yielding "P: P: cause"; this peels each outer layer whose only
+// contribution is to repeat the prefix already present in the wrapped error,
+// leaving a single "P: cause". A layer that adds genuinely new context is kept.
+func cleanProbeError(err error) string {
+	if err == nil {
+		return ""
+	}
+	msg := err.Error()
+	for {
+		inner := errors.Unwrap(err)
+		if inner == nil {
+			break
+		}
+		innerMsg := inner.Error()
+		prefix, ok := strings.CutSuffix(msg, innerMsg)
+		if !ok || prefix == "" || !strings.HasPrefix(innerMsg, prefix) {
+			break
+		}
+		msg, err = innerMsg, inner
+	}
+	return msg
+}
+
+// AlgForKey returns the JWS alg for a public key: EC P-256 -> ES256, RSA -> RS256.
+// The signer backend chooses the key type (the macOS keychain signer uses an
+// RSA-2048 key, hence RS256).
+func AlgForKey(pub crypto.PublicKey) (string, error) {
+	switch k := pub.(type) {
+	case *ecdsa.PublicKey:
+		if k.Curve == elliptic.P256() {
+			return AlgES256, nil
+		}
+		return "", fmt.Errorf("keysigner: unsupported EC curve %q (only P-256/ES256)", k.Curve.Params().Name)
+	case *rsa.PublicKey:
+		return AlgRS256, nil
+	default:
+		return "", fmt.Errorf("keysigner: unsupported public key type %T", pub)
+	}
+}
+
+// ecdsaDERToJOSE converts an ASN.1 DER-encoded ECDSA signature — the form most
+// TEE/TPM backends emit (e.g. facebookincubator/sks marshals the TPM's r,s with
+// asn1.Marshal) — into the fixed-width r||s form JWS requires for ES256
+// (RFC 7518 §3.4). byteLen is the curve coordinate size (32 for P-256), so the
+// result is exactly 2*byteLen bytes with r and s each left-zero-padded.
+//
+// This is intentionally part of the pure-stdlib core (not a platform signer) so
+// it can be unit-tested with a software key on any machine, including TPM-less CI.
+func ecdsaDERToJOSE(der []byte, byteLen int) ([]byte, error) {
+	var sig struct{ R, S *big.Int }
+	rest, err := asn1.Unmarshal(der, &sig)
+	if err != nil {
+		return nil, fmt.Errorf("keysigner: parse ECDSA DER signature: %w", err)
+	}
+	if len(rest) != 0 {
+		return nil, fmt.Errorf("keysigner: %d trailing byte(s) after ECDSA DER signature", len(rest))
+	}
+	if sig.R == nil || sig.S == nil || sig.R.Sign() <= 0 || sig.S.Sign() <= 0 {
+		return nil, fmt.Errorf("keysigner: ECDSA signature has non-positive r/s")
+	}
+	// Guard before FillBytes, which panics if the scalar does not fit in byteLen.
+	if sig.R.BitLen() > byteLen*8 || sig.S.BitLen() > byteLen*8 {
+		return nil, fmt.Errorf("keysigner: ECDSA r/s exceeds %d-byte coordinate", byteLen)
+	}
+	out := make([]byte, 2*byteLen)
+	sig.R.FillBytes(out[:byteLen])
+	sig.S.FillBytes(out[byteLen:])
+	return out, nil
+}
+
+// EncodePublicKey marshals pub to PKIX DER and base64-encodes it (std encoding),
+// matching the public-key form the registration backend binds to the app.
+func EncodePublicKey(pub crypto.PublicKey) (string, error) {
+	der, err := x509.MarshalPKIXPublicKey(pub)
+	if err != nil {
+		return "", fmt.Errorf("keysigner: encode public key: %w", err)
+	}
+	return base64.StdEncoding.EncodeToString(der), nil
+}
+
+// PublicKeyJWK returns the RFC 7517 JSON Web Key for pub, used to embed the
+// public key in the attestation JWT's "jwk" header so the registration backend
+// can bind it to the app. EC keys use base64url fixed-width coordinates
+// (RFC 7518 §6.2.1); RSA keys use base64url-encoded modulus and exponent.
+func PublicKeyJWK(pub crypto.PublicKey) (map[string]any, error) {
+	switch k := pub.(type) {
+	case *ecdsa.PublicKey:
+		if k.Curve != elliptic.P256() {
+			return nil, fmt.Errorf("keysigner: JWK supports EC P-256 only, got %q", k.Curve.Params().Name)
+		}
+		const coordLen = 32 // P-256 field element size
+		x := make([]byte, coordLen)
+		y := make([]byte, coordLen)
+		k.X.FillBytes(x)
+		k.Y.FillBytes(y)
+		return map[string]any{
+			"use": "sig",
+			"kty": "EC",
+			"crv": "P-256",
+			"x":   base64.RawURLEncoding.EncodeToString(x),
+			"y":   base64.RawURLEncoding.EncodeToString(y),
+		}, nil
+	case *rsa.PublicKey:
+		return map[string]any{
+			"use": "sig",
+			"kty": "RSA",
+			"n":   base64.RawURLEncoding.EncodeToString(k.N.Bytes()),
+			"e":   base64.RawURLEncoding.EncodeToString(big.NewInt(int64(k.E)).Bytes()),
+		}, nil
+	default:
+		return nil, fmt.Errorf("keysigner: unsupported public key type %T for JWK", pub)
+	}
+}

internal/keysigner/keysigner_test.go

@@ -0,0 +1,240 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package keysigner
+
+import (
+	"context"
+	"crypto"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"math/big"
+	"reflect"
+	"testing"
+)
+
+func TestAlgForKey(t *testing.T) {
+	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if alg, err := AlgForKey(ec.Public()); err != nil || alg != AlgES256 {
+		t.Errorf("P-256: alg=%q err=%v, want ES256/nil", alg, err)
+	}
+
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if alg, err := AlgForKey(rsaKey.Public()); err != nil || alg != AlgRS256 {
+		t.Errorf("RSA: alg=%q err=%v, want RS256/nil", alg, err)
+	}
+
+	ec384, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := AlgForKey(ec384.Public()); err == nil {
+		t.Error("P-384: expected unsupported-curve error")
+	}
+
+	if _, err := AlgForKey("not a key"); err == nil {
+		t.Error("string: expected unsupported-type error")
+	}
+}
+
+func TestEncodePublicKeyRoundTrip(t *testing.T) {
+	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	enc, err := EncodePublicKey(ec.Public())
+	if err != nil {
+		t.Fatal(err)
+	}
+	der, err := base64.StdEncoding.DecodeString(enc)
+	if err != nil {
+		t.Fatalf("not valid base64: %v", err)
+	}
+	pub, err := x509.ParsePKIXPublicKey(der)
+	if err != nil {
+		t.Fatalf("not valid PKIX: %v", err)
+	}
+	if !reflect.DeepEqual(pub, ec.Public()) {
+		t.Error("public key did not round-trip")
+	}
+}
+
+func TestPublicKeyJWK_EC(t *testing.T) {
+	ec, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	jwk, err := PublicKeyJWK(ec.Public())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if jwk["kty"] != "EC" || jwk["crv"] != "P-256" {
+		t.Errorf("jwk = %v, want kty=EC crv=P-256", jwk)
+	}
+	if jwk["use"] != "sig" {
+		t.Errorf("jwk use = %v, want sig", jwk["use"])
+	}
+	x, _ := jwk["x"].(string)
+	xb, err := base64.RawURLEncoding.DecodeString(x)
+	if err != nil || len(xb) != 32 {
+		t.Errorf("x = %q (decoded %d bytes), want 32-byte base64url", x, len(xb))
+	}
+	if _, ok := jwk["y"].(string); !ok {
+		t.Error("jwk missing y")
+	}
+}
+
+func TestPublicKeyJWK_RSA(t *testing.T) {
+	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		t.Fatal(err)
+	}
+	jwk, err := PublicKeyJWK(rsaKey.Public())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if jwk["kty"] != "RSA" || jwk["n"] == "" || jwk["e"] == "" {
+		t.Errorf("jwk = %v, want kty=RSA with n,e", jwk)
+	}
+	if jwk["use"] != "sig" {
+		t.Errorf("jwk use = %v, want sig", jwk["use"])
+	}
+}
+
+func TestPublicKeyJWK_UnsupportedCurve(t *testing.T) {
+	ec384, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := PublicKeyJWK(ec384.Public()); err == nil {
+		t.Error("P-384: expected error")
+	}
+}
+
+func TestECDSADERToJOSE(t *testing.T) {
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Iterate so we hit signatures whose r or s has its high bit set (ASN.1 pads
+	// those with a leading 0x00) and whose scalars are short (need left-zero
+	// padding) — verifying fixed-width conversion in both directions.
+	for i := 0; i < 64; i++ {
+		digest := sha256.Sum256([]byte{byte(i), byte(i >> 8), 'j', 'w', 't'})
+		der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
+		if err != nil {
+			t.Fatal(err)
+		}
+		jose, err := ecdsaDERToJOSE(der, 32)
+		if err != nil {
+			t.Fatalf("iter %d: %v", i, err)
+		}
+		if len(jose) != 64 {
+			t.Fatalf("iter %d: len(jose)=%d, want 64 (fixed-width r||s)", i, len(jose))
+		}
+		r := new(big.Int).SetBytes(jose[:32])
+		s := new(big.Int).SetBytes(jose[32:])
+		if !ecdsa.Verify(&key.PublicKey, digest[:], r, s) {
+			t.Fatalf("iter %d: converted r||s did not verify against the public key", i)
+		}
+	}
+}
+
+func TestECDSADERToJOSE_Errors(t *testing.T) {
+	if _, err := ecdsaDERToJOSE([]byte{0x01, 0x02, 0x03}, 32); err == nil {
+		t.Error("garbage DER: expected error")
+	}
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	digest := sha256.Sum256([]byte("trailing"))
+	der, err := ecdsa.SignASN1(rand.Reader, key, digest[:])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ecdsaDERToJOSE(append(der, 0x00), 32); err == nil {
+		t.Error("DER with trailing byte: expected error")
+	}
+}
+
+type stubSigner struct{}
+
+func (stubSigner) EnsureKey(context.Context, KeyRef) (crypto.PublicKey, error)  { return nil, nil }
+func (stubSigner) PublicKey(context.Context, KeyRef) (crypto.PublicKey, error)  { return nil, nil }
+func (stubSigner) Sign(context.Context, KeyRef, []byte) ([]byte, string, error) { return nil, "", nil }
+
+func TestCleanProbeError(t *testing.T) {
+	cause := errors.New("open /dev/tpmrm0: permission denied")
+	const p = "sks: error fetching Secure Hardware Vendor Data: "
+
+	// sks double-wraps with the same %w prefix → collapse to a single prefix.
+	doubled := fmt.Errorf(p+"%w", fmt.Errorf(p+"%w", cause))
+	if got, want := cleanProbeError(doubled), p+cause.Error(); got != want {
+		t.Errorf("doubled: got %q, want %q", got, want)
+	}
+	// Triple wrap collapses too.
+	if got, want := cleanProbeError(fmt.Errorf(p+"%w", doubled)), p+cause.Error(); got != want {
+		t.Errorf("tripled: got %q, want %q", got, want)
+	}
+	// A layer adding genuinely new context is preserved.
+	if got, want := cleanProbeError(fmt.Errorf("load: %w", cause)), "load: "+cause.Error(); got != want {
+		t.Errorf("distinct prefix: got %q, want %q", got, want)
+	}
+	// nil and unwrapped-leaf cases.
+	if got := cleanProbeError(nil); got != "" {
+		t.Errorf("nil: got %q, want empty", got)
+	}
+	if got := cleanProbeError(cause); got != cause.Error() {
+		t.Errorf("leaf: got %q, want %q", got, cause.Error())
+	}
+}
+
+type proberSigner struct {
+	stubSigner
+	info HardwareInfo
+}
+
+func (p proberSigner) ProbeHardware(context.Context) (HardwareInfo, error) { return p.info, nil }
+
+func TestProbeHardware(t *testing.T) {
+	// nil signer and a signer that does not implement HardwareProber both yield ok=false.
+	if _, ok, _ := probeHardware(context.Background(), nil); ok {
+		t.Error("nil signer: ok should be false")
+	}
+	if _, ok, _ := probeHardware(context.Background(), stubSigner{}); ok {
+		t.Error("non-prober signer: ok should be false")
+	}
+
+	want := HardwareInfo{Backend: "tpm2", Available: true, VendorName: "ACME"}
+	info, ok, err := probeHardware(context.Background(), proberSigner{info: want})
+	if err != nil || !ok {
+		t.Fatalf("prober: ok=%v err=%v, want true/nil", ok, err)
+	}
+	if info != want {
+		t.Errorf("info = %+v, want %+v", info, want)
+	}
+}
+
+func TestRegistry(t *testing.T) {
+	if Active() != nil {
+		t.Skip("a signer is already registered in this build")
+	}
+	Register(stubSigner{})
+	if _, ok := Active().(stubSigner); !ok {
+		t.Error("Active did not return the registered signer")
+	}
+}

internal/keysigner/registry.go

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package keysigner
+
+import "sync"
+
+var (
+	mu     sync.RWMutex
+	active Signer
+)
+
+// Register sets the active Signer. It is typically called from the init() of a
+// build-tagged or extension package that provides the platform TEE/Keychain
+// implementation. The last registration wins (one backend per platform).
+func Register(s Signer) {
+	mu.Lock()
+	defer mu.Unlock()
+	active = s
+}
+
+// Active returns the registered Signer, or nil if none is available — in which
+// case private_key_jwt is unsupported on this build and only client_secret auth
+// can be used.
+func Active() Signer {
+	mu.RLock()
+	defer mu.RUnlock()
+	return active
+}

internal/keysigner/signer_keychain_darwin.go

@@ -0,0 +1,613 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// macOS non-exportable Keychain signer (compiled into every darwin build).
+//
+// It does NOT use the Secure Enclave / hardware TEE (which would require
+// code-signing entitlements that are unfriendly to open source). Instead it
+// generates an RSA-2048 key in software, imports it into a dedicated app
+// keychain as NON-EXTRACTABLE (`security import -x`), then deletes the software
+// copy — so the private key can sign but can never be exported. Signing is
+// RSASSA-PKCS1v15-SHA256 (RS256).
+//
+// Unlike the original revision, this implementation calls the Security and
+// CoreFoundation frameworks via RUNTIME FFI (github.com/ebitengine/purego)
+// instead of cgo. The security model is identical (the private key is still a
+// non-extractable keychain key and every signature is produced by the OS via
+// SecKeyCreateSignature), but the binary builds with CGO_ENABLED=0 and can be
+// cross-compiled for darwin from any host — so release binaries no longer
+// require a native macOS build runner.
+//
+// Build with:  go build   (cgo-free; compiled into every darwin build, no tag)
+package keysigner
+
+import (
+	"context"
+	"crypto"
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/sha1"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"unsafe"
+
+	"github.com/ebitengine/purego"
+	"github.com/larksuite/cli/internal/vfs"
+)
+
+// ---- Security / CoreFoundation runtime bindings (purego, no cgo) ----
+
+const (
+	cfFrameworkPath  = "/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation"
+	secFrameworkPath = "/System/Library/Frameworks/Security.framework/Security"
+
+	// kCFStringEncodingUTF8 (CFStringBuiltInEncodings).
+	cfStringEncodingUTF8 = 0x08000100
+
+	// OSStatus values.
+	errSecSuccess = 0
+)
+
+var (
+	ffiOnce sync.Once
+	ffiErr  error
+
+	cfDataCreate          func(alloc uintptr, bytes *byte, length int) uintptr
+	cfDataGetLength       func(d uintptr) int
+	cfDataGetBytePtr      func(d uintptr) unsafe.Pointer
+	cfStringCreate        func(alloc uintptr, cstr *byte, encoding uint32) uintptr
+	cfArrayCreate         func(alloc uintptr, values *uintptr, numValues int, cb uintptr) uintptr
+	cfDictCreateMutable   func(alloc uintptr, capacity int, keyCB, valCB uintptr) uintptr
+	cfDictSetValue        func(dict, key, val uintptr)
+	cfRelease             func(ref uintptr)
+	cfErrorGetCode        func(e uintptr) int
+	secKeychainOpen       func(path *byte, out *uintptr) int32
+	secItemCopyMatching   func(query uintptr, result *uintptr) int32
+	secItemUpdate         func(query, attrs uintptr) int32
+	secKeyCreateSignature func(key, algo, data uintptr, errOut *uintptr) uintptr
+
+	// CFTypeRef data-symbol constants (deref to obtain the held ref value).
+	kSecClass                uintptr
+	kSecClassKey             uintptr
+	kSecAttrKeyClass         uintptr
+	kSecAttrKeyClassPrivate  uintptr
+	kSecAttrKeyType          uintptr
+	kSecAttrKeyTypeRSA       uintptr
+	kSecAttrApplicationLabel uintptr
+	kSecReturnRef            uintptr
+	kSecMatchSearchList      uintptr
+	kSecAttrLabel            uintptr
+	kCFBooleanTrue           uintptr
+	algRSAPKCS1SHA256        uintptr
+
+	// Struct-symbol constants (passed BY ADDRESS, not dereferenced).
+	cbTypeArray uintptr
+	cbDictKey   uintptr
+	cbDictValue uintptr
+)
+
+// loadFFI resolves the framework functions and constants once. Any failure
+// (framework missing, symbol absent) is returned to every caller so signing
+// fails cleanly rather than crashing.
+func loadFFI() error {
+	ffiOnce.Do(func() {
+		cf, err := purego.Dlopen(cfFrameworkPath, purego.RTLD_NOW|purego.RTLD_GLOBAL)
+		if err != nil {
+			ffiErr = fmt.Errorf("keysigner: dlopen CoreFoundation: %w", err)
+			return
+		}
+		sec, err := purego.Dlopen(secFrameworkPath, purego.RTLD_NOW|purego.RTLD_GLOBAL)
+		if err != nil {
+			ffiErr = fmt.Errorf("keysigner: dlopen Security: %w", err)
+			return
+		}
+
+		purego.RegisterLibFunc(&cfDataCreate, cf, "CFDataCreate")
+		purego.RegisterLibFunc(&cfDataGetLength, cf, "CFDataGetLength")
+		purego.RegisterLibFunc(&cfDataGetBytePtr, cf, "CFDataGetBytePtr")
+		purego.RegisterLibFunc(&cfStringCreate, cf, "CFStringCreateWithCString")
+		purego.RegisterLibFunc(&cfArrayCreate, cf, "CFArrayCreate")
+		purego.RegisterLibFunc(&cfDictCreateMutable, cf, "CFDictionaryCreateMutable")
+		purego.RegisterLibFunc(&cfDictSetValue, cf, "CFDictionarySetValue")
+		purego.RegisterLibFunc(&cfRelease, cf, "CFRelease")
+		purego.RegisterLibFunc(&cfErrorGetCode, cf, "CFErrorGetCode")
+		purego.RegisterLibFunc(&secKeychainOpen, sec, "SecKeychainOpen")
+		purego.RegisterLibFunc(&secItemCopyMatching, sec, "SecItemCopyMatching")
+		purego.RegisterLibFunc(&secItemUpdate, sec, "SecItemUpdate")
+		purego.RegisterLibFunc(&secKeyCreateSignature, sec, "SecKeyCreateSignature")
+
+		// CFStringRef/CFBooleanRef constants: Dlsym gives the address of the
+		// exported variable; deref once to read the ref it holds.
+		derefs := []struct {
+			dst    *uintptr
+			handle uintptr
+			name   string
+		}{
+			{&kSecClass, sec, "kSecClass"},
+			{&kSecClassKey, sec, "kSecClassKey"},
+			{&kSecAttrKeyClass, sec, "kSecAttrKeyClass"},
+			{&kSecAttrKeyClassPrivate, sec, "kSecAttrKeyClassPrivate"},
+			{&kSecAttrKeyType, sec, "kSecAttrKeyType"},
+			{&kSecAttrKeyTypeRSA, sec, "kSecAttrKeyTypeRSA"},
+			{&kSecAttrApplicationLabel, sec, "kSecAttrApplicationLabel"},
+			{&kSecReturnRef, sec, "kSecReturnRef"},
+			{&kSecMatchSearchList, sec, "kSecMatchSearchList"},
+			{&kSecAttrLabel, sec, "kSecAttrLabel"},
+			{&kCFBooleanTrue, cf, "kCFBooleanTrue"},
+			{&algRSAPKCS1SHA256, sec, "kSecKeyAlgorithmRSASignatureDigestPKCS1v15SHA256"},
+		}
+		for _, d := range derefs {
+			sym, e := purego.Dlsym(d.handle, d.name)
+			if e != nil || sym == 0 {
+				ffiErr = fmt.Errorf("keysigner: dlsym %s: %v", d.name, e)
+				return
+			}
+			// deref of a stable dylib data-symbol address (not Go-managed memory), so safe.
+			*d.dst = *(*uintptr)(unsafe.Pointer(sym)) //nolint:govet // unsafeptr: see comment above
+		}
+
+		// Callback structs are passed by address (no deref).
+		addrs := []struct {
+			dst    *uintptr
+			handle uintptr
+			name   string
+		}{
+			{&cbTypeArray, cf, "kCFTypeArrayCallBacks"},
+			{&cbDictKey, cf, "kCFTypeDictionaryKeyCallBacks"},
+			{&cbDictValue, cf, "kCFTypeDictionaryValueCallBacks"},
+		}
+		for _, a := range addrs {
+			sym, e := purego.Dlsym(a.handle, a.name)
+			if e != nil || sym == 0 {
+				ffiErr = fmt.Errorf("keysigner: dlsym %s: %v", a.name, e)
+				return
+			}
+			*a.dst = sym
+		}
+	})
+	return ffiErr
+}
+
+// cstr returns a pointer to a NUL-terminated copy of s. The backing array stays
+// alive while the returned pointer is reachable.
+func cstr(s string) *byte {
+	b := append([]byte(s), 0)
+	return &b[0]
+}
+
+// cfBytes wraps Go bytes in a CFData (CFDataCreate copies the bytes). Caller
+// releases the returned CFDataRef.
+func cfBytes(b []byte) uintptr {
+	var p *byte
+	if len(b) > 0 {
+		p = &b[0]
+	}
+	d := cfDataCreate(0, p, len(b))
+	runtime.KeepAlive(b)
+	return d
+}
+
+// keychainSearchArray opens the dedicated keychain file and wraps it in a
+// CFArray for kSecMatchSearchList. Caller releases the returned array.
+//
+// NOTE: SecKeychainOpen / the file-based keychain are deprecated by Apple in
+// favor of the data-protection keychain. They still function on current macOS;
+// migrating off them is tracked separately and is independent of the cgo→purego
+// change (the original cgo version used the same APIs).
+func keychainSearchArray(keychainPath string) (uintptr, error) {
+	var kc uintptr
+	if st := secKeychainOpen(cstr(keychainPath), &kc); st != errSecSuccess {
+		return 0, keychainError("open keychain", int(st))
+	}
+	vals := [1]uintptr{kc}
+	arr := cfArrayCreate(0, &vals[0], 1, cbTypeArray)
+	cfRelease(kc) // the array retains it
+	if arr == 0 {
+		return 0, fmt.Errorf("keysigner: CFArrayCreate(search list) failed")
+	}
+	return arr, nil
+}
+
+// findPrivateKey locates the non-extractable private key by its application
+// label within the dedicated keychain. Caller releases the returned SecKeyRef.
+func findPrivateKey(appLabel []byte, keychainPath string) (uintptr, error) {
+	search, err := keychainSearchArray(keychainPath)
+	if err != nil {
+		return 0, err
+	}
+	defer cfRelease(search)
+
+	labelData := cfBytes(appLabel)
+	defer cfRelease(labelData)
+
+	q := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
+	if q == 0 {
+		return 0, fmt.Errorf("keysigner: CFDictionaryCreateMutable(query) failed")
+	}
+	defer cfRelease(q)
+	cfDictSetValue(q, kSecClass, kSecClassKey)
+	cfDictSetValue(q, kSecAttrKeyClass, kSecAttrKeyClassPrivate)
+	cfDictSetValue(q, kSecAttrKeyType, kSecAttrKeyTypeRSA)
+	cfDictSetValue(q, kSecAttrApplicationLabel, labelData)
+	cfDictSetValue(q, kSecReturnRef, kCFBooleanTrue)
+	cfDictSetValue(q, kSecMatchSearchList, search)
+
+	var keyRef uintptr
+	if st := secItemCopyMatching(q, &keyRef); st != errSecSuccess {
+		return 0, keychainError("find private key", int(st))
+	}
+	return keyRef, nil
+}
+
+// securityBin is invoked by absolute path so a poisoned PATH cannot hijack it.
+const securityBin = "/usr/bin/security"
+
+// keychainSigner implements Signer using a macOS non-exportable Keychain key.
+type keychainSigner struct{}
+
+func init() { Register(keychainSigner{}) }
+
+// ProbeHardware reports the macOS Keychain backend backing this signer. The
+// keychain signer is compiled into every darwin build and needs no special
+// hardware, so it reports available whenever the Security tooling is present.
+// It performs no key access, so it never prompts. Implementing HardwareProber
+// is what lets `doctor` report the signer as present rather than treating the
+// (prober-less) signer as "no TEE signer in this build".
+func (keychainSigner) ProbeHardware(_ context.Context) (HardwareInfo, error) {
+	info := HardwareInfo{Backend: "keychain", VendorName: "macOS Keychain"}
+	// A missing security tool is a status (Available=false via Reason), not a
+	// probe error — so we deliberately return a nil error here.
+	if _, err := vfs.Stat(securityBin); err != nil {
+		info.Reason = securityBin + " not found"
+		return info, nil //nolint:nilerr // absence is reported via Reason, not as an error
+	}
+	info.Available = true
+	return info, nil
+}
+
+func (keychainSigner) EnsureKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
+	if md, err := readKeyMetadata(ref.Label); err == nil {
+		return decodePublicKey(md.PublicKey)
+	} else if !os.IsNotExist(err) {
+		return nil, err
+	}
+	return createKeychainKey(ref.Label)
+}
+
+func (keychainSigner) PublicKey(_ context.Context, ref KeyRef) (crypto.PublicKey, error) {
+	md, err := readKeyMetadata(ref.Label)
+	if err != nil {
+		return nil, err
+	}
+	return decodePublicKey(md.PublicKey)
+}
+
+func (keychainSigner) Sign(_ context.Context, ref KeyRef, signingInput []byte) ([]byte, string, error) {
+	if err := loadFFI(); err != nil {
+		return nil, "", err
+	}
+	md, err := readKeyMetadata(ref.Label)
+	if err != nil {
+		return nil, "", err
+	}
+	appLabel, err := hex.DecodeString(md.AppLabel)
+	if err != nil {
+		return nil, "", fmt.Errorf("keysigner: decode app label: %w", err)
+	}
+	if len(appLabel) == 0 {
+		// Guard the &appLabel[0] pointer below against corrupted metadata.
+		return nil, "", fmt.Errorf("keysigner: key metadata for %q has empty app label", ref.Label)
+	}
+	keychain, err := ensureKeychain()
+	if err != nil {
+		return nil, "", err
+	}
+
+	keyRef, err := findPrivateKey(appLabel, keychain)
+	if err != nil {
+		return nil, "", err
+	}
+	defer cfRelease(keyRef)
+
+	digest := sha256.Sum256(signingInput)
+	digestData := cfBytes(digest[:])
+	defer cfRelease(digestData)
+
+	var errRef uintptr
+	sigRef := secKeyCreateSignature(keyRef, algRSAPKCS1SHA256, digestData, &errRef)
+	if sigRef == 0 {
+		code := 0
+		if errRef != 0 {
+			code = cfErrorGetCode(errRef)
+			cfRelease(errRef)
+		}
+		return nil, "", fmt.Errorf("keysigner: SecKeyCreateSignature failed (CFError %d)", code)
+	}
+	defer cfRelease(sigRef)
+
+	n := cfDataGetLength(sigRef)
+	bp := cfDataGetBytePtr(sigRef)
+	out := make([]byte, n)
+	copy(out, unsafe.Slice((*byte)(bp), n))
+	// RS256: the SecKey PKCS1v15-SHA256 signature is the JOSE signature as-is.
+	return out, AlgRS256, nil
+}
+
+// keyMetadata records the public key + the keychain application-label used to
+// locate the non-extractable private key.
+type keyMetadata struct {
+	PublicKey string `json:"public_key"` // PKIX DER, std base64 (see EncodePublicKey)
+	AppLabel  string `json:"app_label"`  // hex(sha1(PKCS1 public key))
+}
+
+func createKeychainKey(label string) (crypto.PublicKey, error) {
+	metadataPath, err := keyMetadataPath(label)
+	if err != nil {
+		return nil, err
+	}
+
+	privateKey, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		return nil, fmt.Errorf("keysigner: generate RSA key: %w", err)
+	}
+	appLabel := sha1.Sum(x509.MarshalPKCS1PublicKey(&privateKey.PublicKey))
+
+	pemFile, err := vfs.CreateTemp("", "lark-keysigner-*.pem")
+	if err != nil {
+		return nil, fmt.Errorf("keysigner: temp key file: %w", err)
+	}
+	pemPath := pemFile.Name()
+	defer vfs.Remove(pemPath)
+	if err := pemFile.Chmod(0600); err != nil {
+		pemFile.Close()
+		return nil, err
+	}
+	der := x509.MarshalPKCS1PrivateKey(privateKey)
+	if _, err := pemFile.WriteString("-----BEGIN RSA PRIVATE KEY-----\n" +
+		base64Wrap(der) + "-----END RSA PRIVATE KEY-----\n"); err != nil {
+		pemFile.Close()
+		return nil, err
+	}
+	if err := pemFile.Close(); err != nil {
+		return nil, err
+	}
+
+	executable, err := vfs.Executable()
+	if err != nil {
+		return nil, fmt.Errorf("keysigner: resolve executable: %w", err)
+	}
+	keychain, err := ensureKeychain()
+	if err != nil {
+		return nil, err
+	}
+	// -x: import as NON-EXTRACTABLE; the software copy (pemPath) is then removed.
+	importCmd := exec.Command(securityBin, "import", pemPath, "-k", keychain, "-t", "priv", "-f", "openssl", "-x", "-A", "-T", executable)
+	if out, err := importCmd.CombinedOutput(); err != nil {
+		return nil, fmt.Errorf("keysigner: import non-extractable key: %w: %s", err, summarizeCmdOutput(out))
+	}
+	if err := setKeychainKeyLabel(appLabel[:], keychain, label); err != nil {
+		return nil, err
+	}
+
+	encodedPub, err := EncodePublicKey(&privateKey.PublicKey)
+	if err != nil {
+		return nil, err
+	}
+	if err := writeKeyMetadata(metadataPath, keyMetadata{PublicKey: encodedPub, AppLabel: hex.EncodeToString(appLabel[:])}); err != nil {
+		return nil, err
+	}
+	return &privateKey.PublicKey, nil
+}
+
+func setKeychainKeyLabel(appLabel []byte, keychain, label string) error {
+	if err := loadFFI(); err != nil {
+		return err
+	}
+	search, err := keychainSearchArray(keychain)
+	if err != nil {
+		return err
+	}
+	defer cfRelease(search)
+
+	labelData := cfBytes(appLabel)
+	defer cfRelease(labelData)
+
+	q := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
+	if q == 0 {
+		return fmt.Errorf("keysigner: CFDictionaryCreateMutable(query) failed")
+	}
+	defer cfRelease(q)
+	cfDictSetValue(q, kSecClass, kSecClassKey)
+	cfDictSetValue(q, kSecAttrKeyClass, kSecAttrKeyClassPrivate)
+	cfDictSetValue(q, kSecAttrKeyType, kSecAttrKeyTypeRSA)
+	cfDictSetValue(q, kSecAttrApplicationLabel, labelData)
+	cfDictSetValue(q, kSecMatchSearchList, search)
+
+	cfLabel := cfStringCreate(0, cstr(label), cfStringEncodingUTF8)
+	if cfLabel == 0 {
+		return fmt.Errorf("keysigner: CFStringCreateWithCString failed")
+	}
+	defer cfRelease(cfLabel)
+	attrs := cfDictCreateMutable(0, 0, cbDictKey, cbDictValue)
+	if attrs == 0 {
+		return fmt.Errorf("keysigner: CFDictionaryCreateMutable(attrs) failed")
+	}
+	defer cfRelease(attrs)
+	cfDictSetValue(attrs, kSecAttrLabel, cfLabel)
+
+	if st := secItemUpdate(q, attrs); st != errSecSuccess {
+		return keychainError("set keychain key label", int(st))
+	}
+	return nil
+}
+
+func decodePublicKey(encoded string) (crypto.PublicKey, error) {
+	der, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil, fmt.Errorf("keysigner: decode public key: %w", err)
+	}
+	return x509.ParsePKIXPublicKey(der)
+}
+
+// base64Wrap PEM-wraps DER bytes at 64 columns.
+func base64Wrap(der []byte) string {
+	enc := base64.StdEncoding.EncodeToString(der)
+	var b strings.Builder
+	for i := 0; i < len(enc); i += 64 {
+		end := i + 64
+		if end > len(enc) {
+			end = len(enc)
+		}
+		b.WriteString(enc[i:end])
+		b.WriteByte('\n')
+	}
+	return b.String()
+}
+
+func readKeyMetadata(label string) (*keyMetadata, error) {
+	path, err := keyMetadataPath(label)
+	if err != nil {
+		return nil, err
+	}
+	data, err := vfs.ReadFile(path)
+	if err != nil {
+		return nil, err // preserves os.ErrNotExist for EnsureKey
+	}
+	var md keyMetadata
+	if err := json.Unmarshal(data, &md); err != nil {
+		return nil, fmt.Errorf("keysigner: parse key metadata: %w", err)
+	}
+	return &md, nil
+}
+
+func writeKeyMetadata(path string, md keyMetadata) error {
+	if err := vfs.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(md, "", "  ")
+	if err != nil {
+		return err
+	}
+	return vfs.WriteFile(path, data, 0600)
+}
+
+func ensureKeychain() (string, error) {
+	keychainPath, err := keychainFilePath()
+	if err != nil {
+		return "", err
+	}
+	password, err := keychainPassword()
+	if err != nil {
+		return "", err
+	}
+	if _, err := vfs.Stat(keychainPath); err != nil {
+		if !os.IsNotExist(err) {
+			return "", fmt.Errorf("keysigner: stat keychain: %w", err)
+		}
+		if err := vfs.MkdirAll(filepath.Dir(keychainPath), 0700); err != nil {
+			return "", err
+		}
+		for _, args := range [][]string{
+			{"create-keychain", "-p", password, keychainPath},
+			{"set-keychain-settings", keychainPath},
+			{"unlock-keychain", "-p", password, keychainPath},
+		} {
+			if out, err := exec.Command(securityBin, args...).CombinedOutput(); err != nil {
+				return "", fmt.Errorf("keysigner: security %s: %w: %s", args[0], err, summarizeCmdOutput(out))
+			}
+		}
+	}
+	return keychainPath, nil
+}
+
+func keysignerDir() (string, error) {
+	configDir, err := os.UserConfigDir()
+	if err != nil {
+		return "", fmt.Errorf("keysigner: resolve config dir: %w", err)
+	}
+	return filepath.Join(configDir, "lark-cli", "keysigner"), nil
+}
+
+func keychainFilePath() (string, error) {
+	dir, err := keysignerDir()
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(dir, "lark-cli.keychain"), nil
+}
+
+func keychainPassword() (string, error) {
+	dir, err := keysignerDir()
+	if err != nil {
+		return "", err
+	}
+	path := filepath.Join(dir, "keychain.pass")
+	if data, err := vfs.ReadFile(path); err == nil {
+		if pw := strings.TrimSpace(string(data)); pw != "" {
+			return pw, nil
+		}
+		return "", fmt.Errorf("keysigner: empty keychain password")
+	} else if !os.IsNotExist(err) {
+		return "", err
+	}
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	pw := hex.EncodeToString(buf)
+	if err := vfs.MkdirAll(filepath.Dir(path), 0700); err != nil {
+		return "", err
+	}
+	if err := vfs.WriteFile(path, []byte(pw+"\n"), 0600); err != nil {
+		return "", err
+	}
+	return pw, nil
+}
+
+func keyMetadataPath(label string) (string, error) {
+	dir, err := keysignerDir()
+	if err != nil {
+		return "", err
+	}
+	id := sha256.Sum256([]byte(label))
+	return filepath.Join(dir, "keys", hex.EncodeToString(id[:])+".json"), nil
+}
+
+// summarizeCmdOutput bounds external command output before it is embedded in
+// an error: first line only, capped at 200 chars.
+func summarizeCmdOutput(out []byte) string {
+	s := strings.TrimSpace(string(out))
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		s = strings.TrimSpace(s[:i])
+	}
+	const maxLen = 200
+	if len(s) > maxLen {
+		s = s[:maxLen] + "..."
+	}
+	return s
+}
+
+func keychainError(operation string, status int) error {
+	switch status {
+	case -25299:
+		return fmt.Errorf("keysigner: %s: key already exists", operation)
+	case -25300:
+		return fmt.Errorf("keysigner: %s: key not found", operation)
+	case -2:
+		return fmt.Errorf("keysigner: %s: allocation failed", operation)
+	default:
+		return fmt.Errorf("keysigner: %s: Security framework status %d", operation, status)
+	}
+}

internal/keysigner/signer_keychain_darwin_test.go

@@ -0,0 +1,62 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package keysigner
+
+import (
+	"context"
+	"crypto"
+	"crypto/rsa"
+	"crypto/sha256"
+	"os"
+	"testing"
+)
+
+// TestKeychainSignerRegistered confirms the keychain_signer build self-registers
+// (init → Register), so keysigner.Active() is non-nil. No keychain access.
+func TestKeychainSignerRegistered(t *testing.T) {
+	if _, ok := Active().(keychainSigner); !ok {
+		t.Fatalf("Active() = %T, want keychainSigner (keychain_signer build must self-register)", Active())
+	}
+}
+
+// TestKeychainSignerRoundTrip creates a real non-extractable RSA key, signs, and
+// verifies RS256 against the returned public key. Gated by LARK_KEYCHAIN_IT
+// because it mutates the dedicated lark-cli keychain store. The signer is now
+// cgo-free (purego runtime FFI), so it runs with CGO_ENABLED=0. Run with:
+//
+//	LARK_KEYCHAIN_IT=1 go test -run RoundTrip ./internal/keysigner/
+func TestKeychainSignerRoundTrip(t *testing.T) {
+	if os.Getenv("LARK_KEYCHAIN_IT") == "" {
+		t.Skip("set LARK_KEYCHAIN_IT=1 to run (mutates the macOS keychain)")
+	}
+	s := keychainSigner{}
+	ref := KeyRef{Label: "lark-cli-keychain-it"}
+
+	pub, err := s.EnsureKey(context.Background(), ref)
+	if err != nil {
+		t.Fatalf("EnsureKey: %v", err)
+	}
+	rsaPub, ok := pub.(*rsa.PublicKey)
+	if !ok {
+		t.Fatalf("public key = %T, want *rsa.PublicKey", pub)
+	}
+	if alg, err := AlgForKey(pub); err != nil || alg != AlgRS256 {
+		t.Fatalf("AlgForKey = %q, %v; want RS256", alg, err)
+	}
+
+	input := []byte("header.payload")
+	sig, alg, err := s.Sign(context.Background(), ref, input)
+	if err != nil {
+		t.Fatalf("Sign: %v", err)
+	}
+	if alg != AlgRS256 {
+		t.Errorf("Sign alg = %q, want RS256", alg)
+	}
+	h := sha256.Sum256(input)
+	if err := rsa.VerifyPKCS1v15(rsaPub, crypto.SHA256, h[:], sig); err != nil {
+		t.Errorf("RS256 signature did not verify: %v", err)
+	}
+}