docs(mail): add identity guidance to prefer user over bot

[chanthuang]

Summary

Add an "identity selection" section to the mail skill documentation, guiding AI agents to default to --as user when operating on mailboxes. Bot identity (--as bot) requires the app to have tenant-level mail scopes enabled in the developer console.

Changes

• skill-template/domains/mail.md: add identity selection section between security rules and typical workflow (template source)
• skills/lark-mail/SKILL.md: same content applied to generated output

Test Plan

• Verified both files have identical identity guidance content
• No code changes, documentation only

Summary by CodeRabbit

• Documentation
  • Enhanced mail access guidance with a new "prefer user identity" section clarifying identity selection for mailbox operations.
  • Stipulated that all write actions (send/reply/forward/draft edit) must use user identity and require prior user login.
  • Clarified read-action guidance: recommend user identity; bot identity permitted only for bulk/application-level reads with required permissions.

[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: 6bf86a32-00ed-4d78-90aa-ff846038a39e

📥 Commits

Reviewing files that changed from the base of the PR and between bfd25ab and 59a417a.

📒 Files selected for processing (2)

• skill-template/domains/mail.md
• skills/lark-mail/SKILL.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skill-template/domains/mail.md

---

📝 Walkthrough

Walkthrough

Added identity-selection guidance to mail docs: prefer --as user for personal mailbox and mandatory for all write operations; allow --as bot only for application-level bulk reads with required permissions; require lark-cli auth login --domain mail before user-scoped actions.

Changes

Cohort / File(s)	Summary
Mail Documentation skill-template/domains/mail.md, skills/lark-mail/SKILL.md	Added "Identity Selection: Prioritize using user identity" section. Specifies --as strategy (default auto), mandates --as user for all write operations and login prerequisite lark-cli auth login --domain mail; allows --as bot only for read/bulk read with proper permissions.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 In inbox meadows I nibble and cheer,
"Use --as user," I whisper near,
Bots peek for batch reads, soft and still,
Writes need a user, login the will,
Hop on, auth done—mail dances with skill.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: adding identity guidance documentation to prefer user identity over bot identity for mail operations.
Description check	✅ Passed	The description provides summary, changes, and test plan sections that are complete. It clearly explains what was added, to which files, and how verification was performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/mail-prefer-user-identity

---

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

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[greptile-apps]

Greptile Summary

This documentation-only PR adds an identity selection section to both the mail skill template and its generated output, guiding AI agents to default to --as user when performing mailbox operations. The added section is logically positioned between the existing security rules and the typical workflow, and the content is identical across both files, correctly maintaining template/output parity.

Key documentation additions:

• Explains the distinction between --as user (recommended, requires prior lark-cli auth login --domain mail) and --as bot (requires developer console permissions; read-only use cases only)
• Provides explicit rules: all write operations (send, reply, forward, draft edit) must use --as user; read operations should prefer --as user but may use --as bot for admin/batch scenarios
• Both skill-template/domains/mail.md and skills/lark-mail/SKILL.md are kept in sync with identical content

Confidence Score: 5/5

Documentation-only change with no code modifications; safe to merge as-is.

Both changed files contain identical, well-structured additions that are consistent with the rest of the document. There are no code changes, no logic regressions, and no factual inaccuracies in the guidance. The template and generated output are correctly kept in sync.

No files require special attention.

Important Files Changed

Filename	Overview
skill-template/domains/mail.md	Adds a new identity selection section between the security rules and typical workflow, guiding AI agents to prefer --as user for all operations and clarifying that bot identity is restricted to read-only use cases.
skills/lark-mail/SKILL.md	Generated SKILL.md receives the same identity selection section as the template; content is byte-for-byte identical to the template addition, maintaining the expected template/output sync.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Mail Operation Request] --> B{Operation Type?}
    B -->|Write: send, reply, forward, draft edit| C[Must use --as user]
    B -->|Read: view mail, inbox list, threads| D{Access Pattern?}
    D -->|Personal / default| E[Prefer --as user]
    D -->|Admin batch / delegated| F[May use --as bot]
    C --> G{User logged in?}
    G -->|No| H[lark-cli auth login --domain mail]
    H --> I[Execute with --as user]
    G -->|Yes| I
    E --> I
    F --> J{App permissions configured?}
    J -->|Yes| K[Execute with --as bot]
    J -->|No| L[Request will be rejected]

Loading

_{Reviews (2): Last reviewed commit: "docs(mail): clarify identity selection w..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skill-template/domains/mail.md`:
- Around line 28-34: The doc currently says "默认使用 `--as user`" which confuses
policy default with the CLI's default; update the wording to state that the
policy recommends explicitly passing `--as user` (i.e., "策略上默认应显式传 `--as user`")
while noting that the CLI flag `--as` itself defaults to `auto`, and adjust the
bullets to reflect: use `--as user` (and run `lark-cli auth login --domain mail`
if not logged in) for personal mailbox access, and use `--as bot` for app-level
batch operations after granting app permissions.

🪄 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: 64c80891-572c-421a-9bf7-38e54cf7dabd

📥 Commits

Reviewing files that changed from the base of the PR and between bdd39b0 and bfd25ab.

📒 Files selected for processing (2)

• skill-template/domains/mail.md
• skills/lark-mail/SKILL.md

[github-actions]

Install this PR change globally:

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@bfd25ab8647e4e9603f51b0c457b3b77d5892e42

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@59a417ae729f5f3ac859d4b86332fe0ebbf3f486

🧩 Skill update

npx skills add larksuite/cli#docs/mail-prefer-user-identity -y -g