@yandy0725/pi-lark 0.1.0

package/skills/lark-im/references/lark-im-card-action-reply.md

@@ -0,0 +1,175 @@
+# card.action.trigger
+
+> **Prerequisite:** Read [`../../lark-event/SKILL.md`](../../lark-event/SKILL.md) first for `event consume` essentials.
+
+Fires when a user interacts with an interactive card — button click, form submit, dropdown select,
+checkbox toggle, date/time pick, etc.
+
+## Setup (required)
+
+> **Console configuration required**: In the Feishu Developer Console, go to
+> **App → Events & Callbacks → Callback Configuration** (应用--事件与回调--回调配置) and enable it.
+> The consumer starts without errors even when not configured, but **no events will be received**.
+> There is no preflight check for this setting.
+
+After enabling, events are delivered over the existing WebSocket long connection — no additional
+URL configuration needed.
+
+## Scopes & auth
+
+| Scope | Required for |
+|---|---|
+| `im:message:readonly` | Auto-fetch `card_content` via message get API (covers both p2p and group messages) |
+
+Auth: `bot` only.
+
+## Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Always `card.action.trigger` |
+| `event_id` | string | Unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms since epoch) |
+| `operator_id` | string (open_id) | Open ID of the user who interacted |
+| `message_id` | string (message_id) | Message ID of the card (`om_xxx`) |
+| `chat_id` | string (chat_id) | Chat ID (`oc_xxx`) |
+| `host` | string | `im_message` (chat card) or `im_top_notice` (top banner) |
+| `token` | string | Delayed-update token; valid 30 min, max 2 uses |
+| `action_tag` | string | Component type that was triggered (see decision table) |
+| `action_value` | string | Developer-defined value on the component; serialized to JSON string |
+| `action_name` | string | `name` attribute of the component |
+| `timezone` | string | User timezone, e.g. `Asia/Shanghai`; only populated for date/time picker interactions |
+| `form_value` | string (JSON) | All form field values as JSON string, keyed by component `name`; only present when a button inside a form container is clicked |
+| `input_value` | string | Input text; only for standalone `input` components (not inside a form) |
+| `option` | string | Selected value for standalone single-select: `select_static`, `select_person`, `overflow`, `date_picker`, `picker_time`, `picker_datetime` |
+| `options` | string | Comma-separated selected values for standalone multi-select: `multi_select_static`, `multi_select_person` |
+| `checked` | bool | Checkbox state for standalone `checker` elements |
+| `card_content` | string | Original card content (userDSL text format) from when the card was sent; auto-fetched via message get API at consume time; empty if `message_id` absent or fetch fails — skip if empty |
+
+## `card_content` — what it is and how to use it
+
+`card_content` is the `user_dsl` field extracted from the card message content, auto-fetched
+at event consume time. It represents the card's original definition — use it as the starting
+point to understand the current card structure and construct the updated card JSON.
+
+No extra API call is needed — the consumer fetches it automatically. If empty, skip — no fallback required.
+
+## action_tag decision table
+
+> **Form container rule**: when a component is inside a `form` container, its value appears in
+> `form_value[name]` instead of the standalone fields (`option`, `options`, `input_value`,
+> `checked`). There is no `form_submit` tag — form submission comes through as `button` with
+> `form_value` populated.
+
+| `action_tag` | Read field(s) | Notes |
+|---|---|---|
+| `button` | `action_value` (fromjson if object); `form_value` if inside a form | Most common; `form_value` non-empty = form submit |
+| `overflow` | `option` | Collapsible button group selection |
+| `select_static` | `option` (standalone) or `form_value[name]` (in form) | Single-select dropdown |
+| `multi_select_static` | `options` (standalone) or `form_value[name]` (in form) | Multi-select dropdown |
+| `select_person` | `option` — open_id of selected user | Single-select person |
+| `multi_select_person` | `options` — comma-separated open_ids | Multi-select person |
+| `input` | `input_value` (standalone) or `form_value[name]` (in form) | Text input |
+| `checker` | `checked` (standalone) or `form_value[name]` (in form) | Checkbox |
+| `date_picker` | `option` (date string) + `timezone` | e.g. `"2024-04-01 +0800"` |
+| `picker_time` | `option` (time string) + `timezone` | e.g. `"08:30 +0800"` |
+| `picker_datetime` | `option` (datetime string) + `timezone` | e.g. `"2024-04-29 07:07 +0800"` |
+| `select_img` | `option` (single) or `options` (multi) | Image picker |
+
+## Key constraints
+
+1. Token **valid 30 minutes**, **max 2 uses** — if update fails after exhaustion, inform the user
+2. Delayed-update API requires **complete new card JSON** — partial updates are not supported
+3. SDK auto-responds `{"code":200}` within 3 s — your update call can be sent any time within 30 min
+4. `card_content` is auto-populated — no extra API call needed; if empty, skip it
+
+## After starting the listener
+
+Once the listener is running, check whether your agent runtime supports background event
+monitoring (i.e. can receive and process stdout lines from a running subprocess while
+continuing to respond to the user). If it does, prompt the user:
+
+> "Card callback listener is now active. Do you want me to automatically handle card
+> interactions and update the card based on user actions?"
+
+Only enter the auto-update workflow below if the user confirms. If your runtime does not
+support background monitoring, inform the user that automatic card updates are not available
+and they will need to handle interactions manually.
+
+## Agent workflow
+
+When a `card.action.trigger` event arrives (**each stdout JSON line is one event — process it immediately**):
+
+```
+1. Read action fields to understand what the user did:
+   - action_tag: which component was triggered
+   - action_value / option / options / checked / input_value / form_value: what value was set
+
+2. Decide: does this interaction require a card update?
+   - e.g. button click with a business action → yes
+   - e.g. navigation / pagination → no (just record, no update needed)
+   - Not every callback requires a card update — decide based on business semantics
+   - Before updating, explicitly state what visual change the action requires. If you cannot articulate one, skip the update.
+
+3. If update is needed:
+   a. If card_content is empty: inform the user that the original card could not be fetched,
+      so it is not possible to determine whether an update is needed — do not guess
+   b. Determine the new card state based on the action
+   c. Use card_content as the structural basis to construct the updated card JSON
+   d. Detect card version: if card_content contains `"schema":"2.0"` or `"schema": "2.0"` it is Card 2.0; otherwise assume Card 1.0
+   e. For Card 1.0: include `"open_ids": ["<operator_id>"]` inside the `card` object, or the API returns code 300090
+   f. Call the delayed update API with the token and new card JSON
+
+4. If no update: end (the SDK has already acknowledged the callback)
+```
+
+## Updating the card
+
+```bash
+lark-cli api POST /open-apis/interactive/v1/card/update --as bot \
+  --data '{"token":"<token>","card":<new_card_json>}'
+```
+
+`--data` parameters:
+
+| Field | Required | Description |
+|---|---|---|
+| `token` | Yes | Delayed-update token from the event |
+| `card` | Yes | Complete new card JSON — construct based on `card_content` from the event, modified to reflect the new state |
+| `card.open_ids` | No | **Card 1.0 only.** Array of `open_id`s defining which users see the updated card. Must contain at least one open_id (e.g. the operator's); passing `[]` or omitting the key both cause "openid empty" (code 300090). |
+
+## Examples
+
+```bash
+# Stream all card interactions
+lark-cli event consume card.action.trigger --as bot
+
+# Grab one callback to inspect shape (debugging only — do not use in production workflows)
+lark-cli event consume card.action.trigger --as bot --max-events 1 --timeout 60s
+
+# Button clicks only (not form submit), with action value
+lark-cli event consume card.action.trigger --as bot \
+  --jq 'select(.action_tag == "button" and .form_value == "") | {op: .operator_id, val: (.action_value | fromjson?), token: .token}'
+
+# Form submits (button with form_value present)
+lark-cli event consume card.action.trigger --as bot \
+  --jq 'select(.action_tag == "button" and .form_value != "") | {op: .operator_id, form: (.form_value | fromjson), token: .token}'
+
+# Date picker interactions
+lark-cli event consume card.action.trigger --as bot \
+  --jq 'select(.action_tag == "date_picker") | {op: .operator_id, date: .option, tz: .timezone}'
+
+# Filter to one chat
+lark-cli event consume card.action.trigger --as bot \
+  --jq 'select(.chat_id == "oc_xxx")'
+```
+
+## Gotchas
+
+- **No `form_submit` tag**: form submission comes as `action_tag = "button"` with `form_value`
+  populated. Check `form_value != ""` to distinguish from a standalone button click.
+- **`action_value` type is developer-defined**: the original may be an object or a plain string.
+  Use `fromjson?` (with `?` to swallow errors) or check before parsing.
+- **Standalone vs form fields**: `input_value`, `option`, `options`, `checked` are only populated
+  for components **not** inside a form container. Inside a form, all values appear in `form_value`.
+- **WebSocket delivery**: no separate callback URL needed; uses the existing WS connection.

package/skills/lark-im/references/lark-im-chat-create.md

@@ -0,0 +1,162 @@
+# im +chat-create
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+Create a group chat. Supports both user identity (`--as user`) and bot identity (`--as bot`). You can specify the group name, description, members (users/bots), owner, chat type (private/public), and group mode. Set `--chat-mode topic` to create a topic chat.
+
+This skill maps to the shortcut: `lark-cli im +chat-create` (internally calls `POST /open-apis/im/v1/chats`).
+
+- `--as bot` requires the `im:chat:create` scope.
+- `--as user` requires the `im:chat:create_by_user` scope.
+
+## Commands
+
+```bash
+# Create a private group (default)
+lark-cli im +chat-create --name "My Group"
+
+# Create a public group (name is required and must be at least 2 characters)
+lark-cli im +chat-create --name "Public Group" --type public
+
+# Create a topic chat
+lark-cli im +chat-create --name "Topic Group" --chat-mode topic
+
+# Specify the group owner
+lark-cli im +chat-create --name "My Group" --owner ou_xxx
+
+# Invite user members (comma-separated open_ids, up to 50)
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb"
+
+# Invite bot members (comma-separated app IDs, up to 5)
+lark-cli im +chat-create --name "My Group" --bots "cli_aaa,cli_bbb"
+
+# Invite both users and bots
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --bots "cli_aaa"
+
+# Make the creating bot a group manager (bot identity only)
+lark-cli im +chat-create --name "My Group" --set-bot-manager --as bot
+
+# JSON output
+lark-cli im +chat-create --name "My Group" --format json
+
+# Create a group with bot identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa" --as bot
+
+# Create a group with user identity
+lark-cli im +chat-create --name "My Group" --users "ou_aaa,ou_bbb" --as user
+
+# Preview the request without creating anything
+lark-cli im +chat-create --name "My Group" --dry-run
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--name <name>` | Required for public groups | Max 60 characters; at least 2 characters for public groups | Group name (`"(no subject)"` for private groups if omitted) |
+| `--description <text>` | No | Max 100 characters | Group description |
+| `--users <ids>` | No | Up to 50, format `ou_xxx` | Comma-separated user open_ids |
+| `--bots <ids>` | No | Up to 5, format `cli_xxx` | Comma-separated bot app IDs |
+| `--owner <open_id>` | No | Format `ou_xxx` | Owner open_id (defaults to the bot when using `--as bot`, or the authorized user when using `--as user`) |
+| `--type <type>` | No | `private` (default) or `public` | Group type. Default to `private`; pass `public` only when the user explicitly asks for a discoverable/public group. |
+| `--chat-mode <mode>` | No | `group` (default) or `topic` | Group mode; `topic` creates a topic chat (not the same as `group_message_type=thread`). When the user asks for a topic chat, pass `topic` explicitly — do not rely on the default. |
+| `--set-bot-manager` | No | - | Set the creating bot as a group manager (only effective with `--as bot`) |
+| `--format json` | No | - | Output as JSON |
+| `--as <identity>` | No | `bot` or `user` | Identity type |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **`--chat-mode topic` vs "normal group with topic-message mode"**: `--chat-mode topic` here creates a 话题群 — the entire group is a topic chat. This is different from "normal group (`chat_mode=group`) + topic-message mode (`group_message_type=thread`)". This CLI exposes only `chat_mode`; `group_message_type` is intentionally not surfaced.
+
+## AI Usage Guidance
+
+### When using `--as bot`
+
+Bot may fail to invite users who are mutually invisible to it during group creation (error 232043). To avoid this, use the **two-step flow** below instead of passing other users' open_ids in `--users`.
+
+1. **Get the current user's open_id:** Run `lark-cli contact +search-user --query "<name or email>"` to retrieve it.
+2. **Create the group — by default include the current user:**
+
+   ```bash
+   lark-cli im +chat-create --name "<group name>" \
+     --users "<current user open_id>" --as bot
+   ```
+
+   **Default behavior:** Always add the current user to the group, unless the user explicitly says "do not add me" or "bot-only group" — only then omit `--users`.
+
+3. **Add other members via user identity** (requires the current user to be in the group):
+
+   ```bash
+   lark-cli im chat.members create \
+     --params '{"chat_id":"<chat_id from step 2>","member_id_type":"open_id","succeed_type":1}' \
+     --data '{"id_list":["ou_aaa","ou_bbb"]}' \
+     --as user
+   ```
+
+   `succeed_type=1` ensures reachable users are added successfully; unreachable ones are returned in `invalid_id_list` instead of failing the whole request.
+
+4. **Check `invalid_id_list`** in the response. If non-empty, report to the user which members could not be added.
+
+### When using `--as user`
+
+User identity does not have the bot visibility limitation, so you can create the group and invite members in one step:
+
+```bash
+lark-cli im +chat-create --name "<group name>" --users "ou_aaa,ou_bbb" --as user
+```
+
+The authorized user is automatically the group creator and member.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | The new group's ID (`oc_xxx` format) |
+| `name` | Group name |
+| `chat_type` | Group type (`private` / `public`) |
+| `owner_id` | Owner ID (may be empty when a bot creates the group and `--owner` is not specified) |
+| `external` | Whether the group is external |
+| `share_link` | Group share link (omitted if retrieval fails) |
+
+## Usage Scenarios
+
+### Scenario 1: Create a group and specify the owner
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" --owner ou_xxx
+```
+
+### Scenario 2: Create a group and invite users and a bot
+
+```bash
+lark-cli im +chat-create --name "Project Discussion Group" \
+  --owner ou_xxx \
+  --users "ou_aaa,ou_bbb" \
+  --bots "cli_aaa"
+```
+
+### Scenario 3: Create a group and send a welcome message
+
+```bash
+CHAT_ID=$(lark-cli im +chat-create --name "New Group" --format json | jq -r '.data.chat_id')
+lark-cli im +messages-send --chat-id "$CHAT_ID" --text "Welcome, everyone!"
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| Permission denied (99991672) | The app does not have `im:chat:create` (bot) or `im:chat:create_by_user` (user) permission enabled | Enable the required permission for the app in the Open Platform console |
+| `--name is required for public groups and must be at least 2 characters` | A public group was created without a name or with a name shorter than 2 characters | Provide a name with at least 2 characters |
+| `--name exceeds the maximum of 60 characters` | The group name is too long | Shorten the name to 60 characters or fewer |
+| `--description exceeds the maximum of 100 characters` | The group description is too long | Shorten the description to 100 characters or fewer |
+| `--users exceeds the maximum of 50` | Too many user members were provided | Split the operation into batches and add more members later |
+| `--bots exceeds the maximum of 5` | Too many bot members were provided | Invite at most 5 bots at once |
+| `invalid user id: expected open_id (ou_xxx)` | Invalid user ID format | Use the `ou_xxx` format for users |
+| `invalid bot id: expected app ID (cli_xxx)` | Invalid bot ID format | Use the `cli_xxx` format for bots |
+| `invalid --owner: expected open_id (ou_xxx)` | Invalid owner ID format | Use the `ou_xxx` format for the owner |
+| `bot is invisible to user` (232043) | The bot and target users are mutually invisible | Follow the two-step flow in AI Usage Guidance above — do not pass other users in `--users` during creation |
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/skills/lark-im/references/lark-im-chat-identity.md

@@ -0,0 +1,55 @@
+# Group Chat Identity Rules
+
+> Warning: The most common source of failure in group operations is choosing the wrong identity. Confirm the identity before performing the action.
+
+Group-chat operations support both `--as user` (UAT user identity) and `--as bot` (TAT bot identity). Choosing the correct identity is critical for success.
+
+## Basic Principles
+
+- **If the user explicitly specifies an identity:** use exactly what the user requested (`--as user` or `--as bot`) without guessing.
+- **If the user does not specify an identity:** infer the correct identity from context instead of relying on the default.
+
+## Identity Selection by Operation
+
+| Operation | Recommended Identity | Why |
+|------|---------|-----------------------------------|
+| Create group (`+chat-create`) | Depends on the scenario | Infer from context |
+| Add members (member-management flow) | `--as user` | Bot visibility is limited and often fails when the target user is mutually invisible to the bot (232024) |
+| Update group (`+chat-update`) | Owner identity | Permission changes require owner/admin privileges; owner transfer requires owner identity |
+
+## Inferring the Owner
+
+When an owner-level action is needed and the owner is unknown, infer in this order:
+
+1. A bot created the group and `--owner` was **not** specified -> the owner is the bot (`--as bot`)
+2. A bot created the group and `--owner ou_xxx` **was** specified -> the owner is that user (`--as user`)
+3. A user created the group and `--owner` was **not** specified -> the owner is the current user (`--as user`)
+4. Still unclear -> ask the user to confirm who owns the group before making owner-level changes
+
+### When the Owner Is Neither the Current User Nor the Bot
+
+If the query shows that the owner is a third-party user (`owner_id` is neither the currently authorized user nor the bot), the current identity does not have owner privileges. In that case:
+
+- **Permission/setting changes:** if the bot is an admin of the group, `--as bot` can still perform admin-level operations such as renaming the group or changing permissions.
+- **Owner-only actions such as owner transfer:** require the actual owner to complete UAT authorization via `lark-cli auth login`, then perform the action as that owner.
+- Explain the limitation clearly to the user instead of retrying blindly.
+
+## Common Pitfalls
+
+### Inviting Members During Group Creation
+
+If a bot creates a group and `--users` includes users who are mutually invisible to the bot, the entire request fails with 232043. Use two steps instead:
+
+1. Create the group with the bot first, excluding invisible users: `lark-cli im +chat-create --name "Group Name"`
+2. Add users later with a user-identity member-management flow
+
+### Insufficient Privileges
+
+- **232016 / 232002 / 232017:** the current identity is not the owner or an admin -> switch to the owner identity
+- **232011:** the current user is not in the group -> use a group-member identity, or join the group first
+- **232024:** the bot and the target user are mutually invisible -> switch to `--as user`
+
+## References
+
+- [lark-im](../SKILL.md) - all IM commands
+- [lark-shared](../../lark-shared/SKILL.md) - authentication and global parameters

package/skills/lark-im/references/lark-im-chat-list.md

@@ -0,0 +1,166 @@
+# im +chat-list
+
+> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
+
+List chats the current user (or bot, with `--as bot`) is a member of. **Not a search API — there is no `--query` parameter; the call always returns the full member list, paginated.** For keyword-based lookup (e.g. find a group by name or by member), use [`+chat-search`](lark-im-chat-search.md) instead.
+
+**Defaults to groups only**; pass `--types=p2p,group` (or `--types p2p --types group`) to also include p2p single chats (user identity only — see ["Bot identity and p2p"](#bot-identity-and-p2p)). Supports pagination, sort order, and (user identity only) muted-chat filtering.
+
+This skill maps to the shortcut: `lark-cli im +chat-list` (internally calls `GET /open-apis/im/v1/chats`).
+
+## Commands
+
+```bash
+# List the user's chats (default sort: create_time, ascending)
+lark-cli im +chat-list
+
+# Sort by recent activity (most recently active first)
+lark-cli im +chat-list --sort active_time
+
+# Limit page size
+lark-cli im +chat-list --page-size 50
+
+# Pagination
+lark-cli im +chat-list --page-token "xxx"
+
+# Drop muted chats (user identity only)
+lark-cli im +chat-list --exclude-muted
+
+# JSON output
+lark-cli im +chat-list --format json
+
+# Preview the request without executing it
+lark-cli im +chat-list --dry-run
+
+# Include p2p single chats (user identity only) — comma form
+lark-cli im +chat-list --as user --types p2p,group
+
+# Same, using repeat flag instead of CSV
+lark-cli im +chat-list --as user --types p2p --types group
+
+# Only p2p single chats (user identity only)
+lark-cli im +chat-list --as user --types p2p
+```
+
+## Parameters
+
+| Parameter | Required | Limits | Description |
+|------|------|------|------|
+| `--user-id-type <type>` | No | `open_id` (default), `union_id`, `user_id` | ID type used for `owner_id` in the response |
+| `--types <strings>` | No | `group`, `p2p` (comma-separated or repeated) | Chat types to include. Omitted = groups only (backward compatible). `p2p` requires user identity (`--as user`); under `--as bot`, `--types=p2p` alone is rejected and `--types=p2p,group` is silently downgraded to `group` |
+| `--sort <field>` | No | `create_time` (default, ascending), `active_time` (descending) | Result ordering |
+| `--page-size <n>` | No | 1-100, default 20 | Number of results per page |
+| `--page-token <token>` | No | - | Pagination token from the previous response |
+| `--exclude-muted` | No | User identity only | Drop chats the current user has muted (do-not-disturb). Under `--as bot`, the flag is silently inactive; see "Filtering muted chats" below |
+| `--format json` | No | - | Output as JSON |
+| `--dry-run` | No | - | Preview the request without executing it |
+
+> **Note:** Supports both `--as user` (default) and `--as bot`. When using bot identity, the app must have bot capability enabled.
+
+## Output Fields
+
+| Field | Description |
+|------|------|
+| `chat_id` | Chat ID (`oc_xxx` format) |
+| `name` | Chat name |
+| `description` | Chat description |
+| `owner_id` | Owner ID (type controlled by `--user-id-type`) |
+| `external` | Whether the chat is external |
+| `chat_status` | Chat status (`normal` / `dissolved` / `dissolved_save`) |
+| `chat_mode` | Chat mode discriminator: `group` (regular) / `topic` (topic group) / `p2p` (single chat) |
+| `p2p_target_type` | Peer type, e.g., `user` |
+| `p2p_target_id` | Peer ID (type controlled by `--user-id-type`) |
+
+## Including p2p single chats
+
+Default behavior lists groups only — same as before this feature. To include p2p, pass `--types`:
+
+| User intent | Call | Identity |
+|---|---|---|
+| "list my groups" / 我的群 / 我加入了哪些群 | (default, omit `--types`) | user or bot |
+| "list my p2p chats" / 我的单聊 / 我跟谁有 1v1 | `--types p2p` | **user only** |
+| "all my chats" / 全部聊天 / 所有会话 (ambiguous) | `--types p2p,group` | **user only** |
+
+For p2p rows in the response: `name` is the peer's display name, `owner_id` follows group semantics, `chat_mode = "p2p"`, and `p2p_target_type` / `p2p_target_id` identify the peer.
+
+## Bot identity and p2p
+
+`tenant_access_token` cannot list p2p chats — to protect user privacy, bot identity is not permitted to enumerate p2p single chats. Behavior under `--as bot`:
+
+- `--as bot --types=p2p` → rejected at validation time with an actionable error; no request is sent.
+- `--as bot --types=p2p,group` → CLI strips `p2p` and sends `types=group`. Request proceeds; only groups are returned. The strip is a **request-level adjustment**, surfaced two ways so neither humans nor agents miss it:
+    - **stderr**: `warning: bot_strip_p2p: To protect user privacy, bot identity cannot list p2p chats; --types=p2p,group was sent as types=group. Use --as user to include p2p.` (matches the `warning: <code>: <message>` convention in `shortcuts/common/runner.go`)
+    - **stdout JSON**: a top-level `notices` array gains a structured entry:
+      ```json
+      {
+        "chats": [...],
+        "notices": [
+          { "code": "bot_strip_p2p", "message": "To protect user privacy, bot identity cannot list p2p chats; …" }
+        ]
+      }
+      ```
+    - The `filter` slot stays scoped to `--exclude-muted`; `notices` is a separate top-level key, so the two never collide and no priority is needed when both fire.
+    - DryRun emits the same stderr warning so a previewed request truthfully reflects what Execute will send (parity with `shortcuts/drive/drive_search.go`).
+- `--as bot --types=group` → accepted, returns groups normally.
+- `--as bot` (no `--types`) → unchanged, returns groups.
+
+To include p2p single chats, switch to user identity: `--as user --types=p2p,group`.
+
+## Filtering muted chats
+
+`--exclude-muted` (user identity only) drops chats the current user has set to do-not-disturb. After the list call, the CLI batches the page's chat_ids through `POST /open-apis/im/v1/chat_user_setting/batch_get_mute_status` and filters client-side. Under `--as bot`, the mute API is UAT-only and the filter is silently skipped.
+
+When the flag is set, the JSON envelope gains a `filter` sub-object (absent otherwise, so existing consumers are unaffected); `fetched_count == returned_count + filtered_count` always holds:
+
+```json
+{
+  "chats": [...],
+  "filter": {
+    "applied": "exclude_muted",
+    "fetched_count": 20,
+    "returned_count": 17,
+    "filtered_count": 3,
+    "hint": "Filtered out 3 muted chat(s) on this page (17 remaining); use --page-token to fetch more."
+  }
+}
+```
+
+## Usage Scenarios
+
+### Scenario 1: List my recent chats
+
+```bash
+lark-cli im +chat-list --sort active_time --page-size 10
+```
+
+### Scenario 2: List my non-muted chats sorted by activity
+
+```bash
+lark-cli im +chat-list --sort active_time --exclude-muted
+```
+
+### Scenario 3: Iterate all my chats programmatically
+
+```bash
+TOKEN=""
+while :; do
+  RESP=$(lark-cli im +chat-list --page-size 100 --page-token "$TOKEN" --format json)
+  echo "$RESP" | jq -r '.data.chats[].chat_id'
+  HAS_MORE=$(echo "$RESP" | jq -r '.data.has_more')
+  [ "$HAS_MORE" = "true" ] || break
+  TOKEN=$(echo "$RESP" | jq -r '.data.page_token')
+done
+```
+
+## Common Errors and Troubleshooting
+
+| Symptom | Root Cause | Solution |
+|---------|---------|---------|
+| `--page-size must be an integer between 1 and 100` | page-size is out of range or not an integer | Use an integer between 1 and 100 |
+| Permission denied (99991672) | The bot app does not have `im:chat:read` TAT permission enabled | Enable the permission for the app in the Open Platform console |
+| Permission denied (99991679) with `--as user` | UAT is not authorized for `im:chat:read` | Run `lark-cli auth login --scope "im:chat:read"` |
+| `Bot ability is not activated` (232025) | The app does not have bot capability enabled | Enable bot capability in the Open Platform console |
+| `--exclude-muted` returns all chats unfiltered and `hint` says "no effect under bot identity" | Running under `--as bot` (mute API is UAT-only) | Switch to `--as user` for mute filtering |
+| `--types=p2p (single chats) is only supported with user identity` | `--as bot` + `--types=p2p` (single-value only; mixed `--types=p2p,group` is downgraded to `group` and surfaces a `bot_strip_p2p` notice via stderr + `outData["notices"]` — see "Bot identity and p2p") | Use `--as user`, or include `group` in `--types` (the bot proceeds with `group` only and emits the `bot_strip_p2p` notice) |
+
+> Full error message of the row above: `--types=p2p (single chats) is only supported with user identity (--as user). To protect user privacy, bot identity cannot list p2p chats. Use --as user, or include "group" in --types.`