feat: add scope catalog and batch-import JSON generator

[zjsng]

Problem

Setting up a Lark app requires manually toggling dozens of API scopes in the admin console — separately for tenant and user access tokens. Contributors don't know which scopes each CLI command needs, and getting it wrong means cryptic API errors at runtime.

Additionally, commands using tenant_access_token (msg send, chat search, contact get) were incorrectly pre-validated against the user token's scope string, which never contains tenant-granted scopes. This caused false "missing permissions" errors even when the app was correctly configured.

Solution

Add lark auth scopes --json-import to generate the batch-import JSON for Lark's app scope configuration page, and fix scope validation to only check what it can actually verify.

For users setting up a Lark app: Generate the exact scopes your app needs and paste them into the admin console:

# All CLI features
lark auth scopes --json-import

# Only specific groups
lark auth scopes --json-import --groups calendar,documents

For contributors adding new commands: Scope data lives in two files by design:

File	What to edit	When
scopes.go	OAuth scopes (minimal, ~27 total)	Adding a command that needs user-token API access
catalog.go	App config scopes (comprehensive)	Adding scopes to the batch-import JSON output

Commands using user tokens (cal, doc, sheet, bitable, minutes) keep PersistentPreRun scope validation. Commands using tenant tokens (msg, chat, contact get/list-dept) skip it — the API surfaces permission errors directly.

What's included

Batch-import JSON generator (internal/scopes/catalog.go)

• Comprehensive tenant/user scope data derived from the API docs (PR feat: add local Lark API docs for AI-agent-assisted development #28)
• lark auth scopes --json-import [--groups ...] outputs Lark's expected format:

{
  "scopes": {
    "tenant": ["calendar:calendar", "calendar:calendar:readonly", "..."],
    "user": ["calendar:calendar.event:read", "offline_access", "..."]
  }
}

Scope validation fixes (internal/cmd/{msg,chat,contact,mail}.go)

• Removed PersistentPreRun scope checks from tenant-token commands — these checked user token scopes for commands that use tenant tokens
• Added per-subcommand PreRun on contact search and contact search-dept (the two contact subcommands that actually use user tokens)

Cleanup

• Removed unused --add flag from auth login (was defined but never wired up)
• Fixed stale --add --scopes references across USAGE.md, CLAUDE.md, and all 8 skill files
• Added bitable to scope groups table in USAGE.md
• Updated mail group description to clarify IMAP app password relationship

Test plan

• lark auth scopes --json-import generates valid JSON with tenant/user split
• lark auth scopes --json-import --groups calendar filters to specific group
• lark auth scopes --json-import --groups invalid errors with guidance
• lark auth login --help no longer shows --add flag
• Tenant-token commands (msg send, contact get) no longer show false scope errors
• User-token commands (cal list, doc get) still validate scopes correctly
• grep -r "\-\-add" USAGE.md CLAUDE.md skills/ returns nothing

🤖 Generated with Claude Code