docs(auth): explain pending scope request carryover

[xu91102]

Fixes #1493

背景

用户已按最小 scope 发起授权，但开发者后台仍显示历史常用权限时，重复登录不会清理后台遗留的待审批申请。

核心改动

• 说明后台遗留申请可能被合并展示的原因。
• 引导管理员在后台取消、驳回或处理旧申请。
• 明确 CLI 无法替代管理员清理后台申请，并要求用 auth status 验证最终 scope。

验证

• go test ./internal/qualitygate/rules -count=1
• git diff --check

风险与回滚

仅补充 Skill 运行指引，不改变 CLI 命令或 API 行为。回滚本提交即可恢复原文档。

Summary by CodeRabbit

• Documentation
  • Added guidance for handling previously requested permissions after minimal-scope authorization.
  • Clarified not to repeatedly re-run authorization with different scopes.
  • Included steps to clear/handle pending or historical requests and verify actually granted permissions via CLI status output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cbcb6fbd-7f71-4148-8f8c-1ddd5cbeec09

📥 Commits

Reviewing files that changed from the base of the PR and between efa6b77 and 1a32f61.

📒 Files selected for processing (1)

• skills/lark-shared/SKILL.md

✅ Files skipped from review due to trivial changes (1)

• skills/lark-shared/SKILL.md

---

📝 Walkthrough

Walkthrough

The shared lark-cli skill documentation explains how to handle previously requested permissions after minimal-scope authorization and verify the scopes actually granted.

Changes

Authorization documentation

Layer / File(s)	Summary
Minimal-scope authorization guidance skills/lark-shared/SKILL.md	Documents handling pending or historical authorization requests through the developer backend before re-running minimal-scope login and verifying granted scopes.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• larksuite/cli#1598: Updates shared authorization documentation covering minimal-scope login and permission verification.
• larksuite/cli#1654: Modifies shared authentication documentation for authorization and login flows.
• larksuite/cli#1794: Adds related guidance for minimal-scope authorization and shared skill documentation.

Suggested labels: documentation, domain/ccm

Suggested reviewers: albertnusouo, liangshuo-1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the doc change about pending scope request carryover.
Description check	✅ Passed	It covers motivation, core changes, verification, and rollback, though the headings don't match the template exactly.
Linked Issues check	✅ Passed	The docs address #1493 by explaining the carryover behavior, cleanup guidance, and scope verification workflow.
Out of Scope Changes check	✅ Passed	The PR stays within documentation changes and introduces no unrelated code or behavior changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skills/lark-shared/SKILL.md`:
- Line 93: Update the documented verification command in the CLI authentication
guidance to use the supported `auth status` JSON flag, replacing the invalid
`--format json` usage while preserving the existing `--verify` behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 43e8a4e8-2397-4823-923f-6377b1c373da

📥 Commits

Reviewing files that changed from the base of the PR and between 4847f06 and efa6b77.

📒 Files selected for processing (1)

• skills/lark-shared/SKILL.md

[xu91102]

@coderabbitai 已处理：已用本仓库 go run . auth status --help 验证，结构化输出的受支持参数是 --json。文档现使用 lark-cli auth status --verify --json。已运行 go test ./internal/qualitygate/rules -count=1 与 git diff --check。

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@xu91102 Thanks for verifying against auth status --help and updating the docs to use --json. Confirmed and validated with the test suite and git diff --check. 🐰✅

---

✏️ Learnings added

Learnt from: xu91102
URL: https://github.com/larksuite/cli/pull/1855

Timestamp: 2026-07-11T17:29:42.936Z
Learning: In the lark-cli repository (larksuite/cli), the `auth status` command's structured output flag is `--json` (not `--format json`). Example usage: `lark-cli auth status --verify --json`. This was confirmed via `go run . auth status --help`.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.