@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-event/references/lark-event-approval.md

@@ -0,0 +1,170 @@
+# Approval Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (2)
+
+| EventKey | Purpose |
+|---|---|
+| `approval.instance.status_changed_v4` | An approval instance status changed |
+| `approval.task.status_changed_v4` | An approval task status changed |
+
+Both keys use a **Custom schema**. The raw Lark schema 2.0 envelope is flattened: event metadata is exposed as `type`, `event_id`, and `timestamp`, while approval business fields are exposed at the top level.
+
+Both keys carry a **PreConsume hook** that subscribes the current authorized user through the Approval subscription APIs before listening. The consumer intentionally does **not** unsubscribe on exit; the server-side Approval subscription relation remains until it is canceled outside `event consume`. These keys require `--as user`.
+
+## Listener and subscription selection
+
+At the raw CLI level, each `event consume` process accepts exactly one EventKey. `approval.instance.status_changed_v4` and `approval.task.status_changed_v4` have different output shapes, so listening to both still means two processes.
+
+For Approval only, `subscription_type` is an optional setup param used by PreConsume to register server-side Approval subscription relations before the local listener starts. It is **not** an output field, a local event filter, or a local subscription identity. The pushed event does not say which subscription relation caused delivery, and one business event can match both relations; deduplicate with `event_id` when needed.
+
+`subscription_type` may be omitted, a single value, a comma-separated list, or a JSON string array:
+
+```bash
+# Omitted: register both INVOLVED_APPROVAL and MANAGED_APPROVAL for this EventKey
+lark-cli event consume approval.instance.status_changed_v4 --as user
+
+# Single relation
+lark-cli event consume approval.instance.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user
+
+# Explicit multi-relation registration for one local consumer
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
+  --as user
+
+# JSON array form; quote it for the shell
+lark-cli event consume approval.task.status_changed_v4 \
+  -p 'subscription_type=["INVOLVED_APPROVAL","MANAGED_APPROVAL"]' \
+  --as user
+```
+
+| Value | Meaning |
+|---|---|
+| `INVOLVED_APPROVAL` | Receive events where the current user is the approval requester or approver |
+| `MANAGED_APPROVAL` | Receive events under approval definitions managed by the current user |
+
+User-intent inference:
+
+| User intent | EventKey(s) | `subscription_type` |
+|---|---|---|
+| Mentions approval instances, approval forms, approval order/status, or "instance status" | `approval.instance.status_changed_v4` | infer from relation words below |
+| Mentions approval tasks, approval todo items, approver operations, or "task status" | `approval.task.status_changed_v4` | infer from relation words below |
+| Says "approval status changes/events" without saying task vs instance | both EventKeys | infer from relation words below |
+| Says "my approvals", "approvals involving me", "I requested/approved", "待我审批", "我发起/我参与" | requested EventKey(s) | `INVOLVED_APPROVAL` |
+| Says "approvals I manage", "managed definitions", "definitions managed by me", "我管理的审批定义" | requested EventKey(s) | `MANAGED_APPROVAL` |
+| Explicitly asks for both involved and managed, or says "all approval subscriptions" | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type`, or pass both values in one `-p` |
+| Relation is ambiguous and the user wants broad coverage | requested EventKey(s), or both if EventKey is also ambiguous | omit `subscription_type` so PreConsume registers both |
+
+If the user's wording omits the relation and broad listening is acceptable, omit `subscription_type`. Ask only when registering both relations would be materially harmful.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `approval.instance.status_changed_v4` | `approval:instance:read` | user |
+| `approval.task.status_changed_v4` | `approval:task:read` | user |
+
+## Subscription behavior
+
+Startup calls the endpoint for the selected EventKey:
+
+```text
+POST /open-apis/approval/v4/instances/subscription
+POST /open-apis/approval/v4/tasks/subscription
+```
+
+For each resolved `subscription_type`, PreConsume sends one request body:
+
+```json
+{"subscription_type":"INVOLVED_APPROVAL"}
+```
+
+If `subscription_type` is omitted, PreConsume sends two registration requests for that EventKey: one with `INVOLVED_APPROVAL`, then one with `MANAGED_APPROVAL`. If listening to both instance and task events, run two consumers; each consumer may omit `subscription_type` to register both relations for its own EventKey.
+
+Do not start two consumers for the same Approval EventKey merely to split `INVOLVED_APPROVAL` and `MANAGED_APPROVAL`. The server push and flattened output are keyed by EventKey and cannot be distinguished by subscription relation.
+
+Shutdown behavior:
+
+`event consume` does not call the Approval unsubscribe APIs when it exits. This applies to graceful exit, Ctrl+C / SIGTERM, stdin EOF, `--timeout`, and `--max-events`.
+
+To stop future delivery for a user, cancel the Approval subscription relation outside this consumer. The unsubscribe APIs are separate operations and are not called by `event consume`.
+
+## Output fields
+
+Common fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type |
+| `event_id` | string | Globally unique event ID; use for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time in milliseconds, taken from `header.create_time` |
+
+Instance event fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `approval_code` | string | Approval definition code; not a subscription dimension |
+| `instance_code` | string | Approval instance code |
+| `external_id` | string | Third-party approval instance id, when present |
+| `status` | string enum | `PENDING`, `APPROVED`, `REJECTED`, `CANCELED`, `DELETED`, `REVERTED`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
+| `operate_time` | string (timestamp_ms) | Status change time |
+| `start_user` | object | Instance starter user IDs, omitted when unavailable |
+| `start_user.open_id` | string (open_id) | Instance starter open_id, when present |
+| `start_user.union_id` | string (union_id) | Instance starter union_id, when present |
+| `start_user.user_id` | string (user_id) | Instance starter tenant user_id, when present |
+
+Task event fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `approval_code` | string | Approval definition code; not a subscription dimension |
+| `instance_code` | string | Approval instance code |
+| `task_id` | string | Approval task id |
+| `external_id` | string | Third-party approval external id, when present |
+| `task_external_id` | string | Third-party task external id, when emitted |
+| `assigned_user` | object | Task assignee or operator user IDs, omitted for automatic flows without an operator |
+| `assigned_user.open_id` | string (open_id) | Task assignee or operator open_id, when present |
+| `assigned_user.union_id` | string (union_id) | Task assignee or operator union_id, when present |
+| `assigned_user.user_id` | string (user_id) | Task assignee or operator tenant user_id, when present |
+| `status` | string enum | `REVERTED`, `PENDING`, `APPROVED`, `REJECTED`, `TRANSFERRED`, `ROLLBACK`, `DONE`, `OVERTIME_CLOSE`, `OVERTIME_RECOVER` |
+| `operate_time` | string (timestamp_ms) | Status change time |
+
+## Examples
+
+```bash
+# Stream approval instance updates broadly; registers both involved and managed relations
+lark-cli event consume approval.instance.status_changed_v4 \
+  --as user
+
+# Stream approval instance updates only for approvals involving the current user
+lark-cli event consume approval.instance.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user
+
+# Stream approval task updates for definitions managed by the current user
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=MANAGED_APPROVAL \
+  --as user
+
+# Broad approval status listening:
+# run both EventKeys as separate processes; omit subscription_type so each registers both relations.
+lark-cli event consume approval.instance.status_changed_v4 \
+  --as user > approval-instance.ndjson &
+lark-cli event consume approval.task.status_changed_v4 \
+  --as user > approval-task.ndjson &
+wait
+
+# Listen to both involved and managed task subscriptions with one local consumer.
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL,MANAGED_APPROVAL \
+  --as user > approval-task.ndjson
+
+# Project a compact approval-task record
+lark-cli event consume approval.task.status_changed_v4 \
+  -p subscription_type=INVOLVED_APPROVAL \
+  --as user \
+  --jq '{event_id, task_id, status, at: .operate_time}'
+```

package/skills/lark-event/references/lark-event-im.md

@@ -0,0 +1,87 @@
+# IM Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+>
+> **Heads-up for AI agents**: this key's `.content` is **NOT** the raw OAPI payload shape your training data may suggest. `lark-cli` runs a Process hook (`convertlib`) that flattens the V2 envelope and **pre-renders** `.content` to human-readable text for `text` / `post` / `image` / `file` / `audio` / etc. Only `interactive` (cards) keeps the raw JSON string. Don't blindly `fromjson`.
+
+## Key catalog (12)
+
+| EventKey | Purpose |
+|---|---|
+| `im.message.receive_v1` | Receive IM messages |
+| `im.message.message_read_v1` | User read a bot's **p2p** message (group messages don't fire this) |
+| `im.message.reaction.created_v1` | Reaction added to a message |
+| `im.message.reaction.deleted_v1` | Reaction removed from a message |
+| `im.chat.updated_v1` | Chat settings changed (owner, avatar, name, permissions, etc.) |
+| `im.chat.disbanded_v1` | Chat disbanded |
+| `im.chat.member.bot.added_v1` | Bot added to a chat |
+| `im.chat.member.bot.deleted_v1` | Bot removed from a chat |
+| `im.chat.member.user.added_v1` | User joined a chat (including topic chats) |
+| `im.chat.member.user.deleted_v1` | User left voluntarily **or** was removed |
+| `im.chat.member.user.withdrawn_v1` | Pending chat invite withdrawn (inviter canceled; user never actually joined) |
+| `card.action.trigger` | Interactive card callback — button click, form submit, dropdown, etc. → see [`lark-im-card-action-reply.md`](../../lark-im/references/lark-im-card-action-reply.md) |
+
+> **Shape**: All 12 events have a V2-enveloped raw payload. `lark-cli` flattens two of them — `im.message.receive_v1` and `card.action.trigger` — so their consumed output is flat (fields at `.xxx`). The other 10 are passed through as-is; use `.event.xxx` to access their fields.
+
+## Gotchas (`im.message.receive_v1`)
+
+**sender_id is open_id only**: the event payload carries no display name. Call the contact API separately if you need the sender's name.
+
+**`.content` shape depends on `message_type`** (this key uses a flat Custom schema; see [`events/im/message_receive.go`](../../../events/im/message_receive.go)):
+
+| message_type | `.content` shape | How to read |
+|---|---|---|
+| `text` / `post` / `image` / `file` / `audio` / `sticker` / `share_chat` / `share_user` / `media` / `system` | Human-readable text (convertlib-processed; `@mentions` resolved to display names) | Use `.content` directly |
+| `interactive` (card) | Raw card JSON string (structured actions can't be losslessly flattened) | `.content \| fromjson` to get the card object |
+
+**Do not blindly `fromjson`** — for non-interactive messages it fails with `jq: fromjson cannot be applied to "hello"` because `.content` isn't JSON-encoded.
+
+```bash
+# text: .content is plain text — no fromjson needed
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+
+# interactive: .content is a JSON string — fromjson to parse
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+
+## On-demand filter recipes
+
+> **Default = no `--jq`.** Run `lark-cli event consume im.message.receive_v1 --as bot` to see every message. The recipes below are only for cases where the user has asked to narrow the stream.
+
+### 1. Filter by chat type (p2p vs group)
+
+`chat_type` is an enum with values `p2p` / `group`.
+
+```bash
+# p2p only (direct messages)
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="p2p") | {from: .sender_id, msg: .content}'
+
+# group only
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.chat_type=="group") | {chat: .chat_id, from: .sender_id, msg: .content}'
+```
+
+### 2. Filter by message type
+
+```bash
+# text only — content is plain human-readable text
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="text") | .content'
+
+# interactive (card) only — parse the card body
+lark-cli event consume im.message.receive_v1 --as bot \
+  --jq 'select(.message_type=="interactive") | .content | fromjson'
+```
+
+### 3. Filter by sender (only one user's messages)
+
+```bash
+# example: only messages from the given open_id
+lark-cli event consume im.message.receive_v1 --as bot\
+  --jq 'select(.sender_id=="ou_xxxxxxxxxxxxxxxxxxxxxxxxxx") | {msg_id: .message_id, text: .content}'
+```
+
+Get your own open_id via `lark-cli contact +get-user --as user`; other users' via `lark-cli contact +search-user`.

package/skills/lark-event/references/lark-event-minutes.md

@@ -0,0 +1,54 @@
+# Minutes Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (1)
+
+| EventKey | Purpose |
+|---|---|
+| `minutes.minute.generated_v1` | A minute (妙记) has been generated |
+
+This key uses a **Custom schema** (flat output at `.xxx`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `minutes.minute.generated_v1` | `minutes:minutes.basic:read` | user |
+
+Requires `--as user`.
+
+## `minutes.minute.generated_v1`
+
+### Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type; always `minutes.minute.generated_v1` |
+| `event_id` | string | Globally unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
+| `minute_token` | string | Minute token |
+| `title` | string | Minute title (enriched via detail API) |
+| `minute_source` | object | Minute source metadata; only present when the source is a meeting |
+| `minute_source.source_type` | string | Source type; only present when the source is a meeting (value: `meeting`) |
+| `minute_source.source_entity_id` | string | Source entity ID (meeting ID); only present when the source is a meeting |
+
+### Enrichment & degradation
+
+The Process hook calls `GET /open-apis/minutes/v1/minutes/{minute_token}` to enrich `title`. If the detail API fails, this field is left empty — the base fields (`type`, `event_id`, `timestamp`, `minute_token`, `minute_source`) are always present.
+
+`minute_source` is populated from the event payload directly (not the detail API), so it survives enrichment failures. Note: `minute_source` is only present when the minute originates from a meeting; for other sources (e.g. recording, local upload) this field is absent.
+
+### Example
+
+```bash
+lark-cli event consume minutes.minute.generated_v1 --as user
+
+# Project title and token only (skip events where enrichment failed)
+lark-cli event consume minutes.minute.generated_v1 --as user \
+  --jq 'select(.title != "") | {minute_token, title}'
+
+# Filter by source type
+lark-cli event consume minutes.minute.generated_v1 --as user \
+  --jq 'select(.minute_source.source_type == "meeting") | {minute_token, title}'
+```

package/skills/lark-event/references/lark-event-task.md

@@ -0,0 +1,78 @@
+# Task Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (1)
+
+| EventKey | Purpose |
+|---|---|
+| `task.task.update_user_access_v2` | A visible task has been created, deleted, or updated |
+
+This key uses a **Native schema** (V2 envelope; output rooted at `.event`) and carries a **PreConsume hook** that calls the Task event subscription API before listening.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `task.task.update_user_access_v2` | `task:task:read` | user, bot |
+
+Supports `--as user` or `--as bot`.
+
+- `--as user`: receive task updates visible to the current user through authorship, assignment, following, or other access.
+- `--as bot`: receive task updates for tasks the application is responsible for.
+
+## `task.task.update_user_access_v2`
+
+### Subscription behavior
+
+On startup, `event consume` calls:
+
+```text
+POST /open-apis/task/v2/task_v2/task_subscription?user_id_type=open_id
+```
+
+The Task subscription API has no matching unsubscribe endpoint in the current CLI metadata, so graceful exit has no cleanup call for this EventKey. Re-running the consumer repeats the subscribe call for the selected identity.
+
+This EventKey is single-consumer per local bus subscription: start one `event consume task.task.update_user_access_v2` process for a given app/profile/identity at a time.
+
+### Output fields (V2 envelope; root path `.event`)
+
+| Field | Type | Description |
+|---|---|---|
+| `.header.event_id` | string | Globally unique event ID; safe for deduplication |
+| `.header.create_time` | string (timestamp_ms) | Event creation time in milliseconds |
+| `.event.event_types[]` | string enum | Task commit types included in this event |
+| `.event.task_guid` | string (kind=task_guid) | Task GUID that changed |
+
+Commit types:
+
+```text
+task_assignees_update
+task_completed_update
+task_create
+task_deleted
+task_desc_update
+task_followers_update
+task_reminders_update
+task_start_due_update
+task_summary_update
+```
+
+### Example
+
+```bash
+# Stream task update events for the current user
+lark-cli event consume task.task.update_user_access_v2 --as user
+
+# Sample one event for payload inspection
+lark-cli event consume task.task.update_user_access_v2 \
+  --as user --max-events 1 --timeout 2m
+
+# Project to a compact task-update record
+lark-cli event consume task.task.update_user_access_v2 \
+  --as user \
+  --jq '{event_id: .header.event_id, task_guid: .event.task_guid, event_types: .event.event_types, timestamp: .header.create_time}'
+
+# Consume as the app identity
+lark-cli event consume task.task.update_user_access_v2 --as bot
+```

package/skills/lark-event/references/lark-event-vc.md

@@ -0,0 +1,106 @@
+# VC Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (4)
+
+| EventKey | Purpose |
+|---|---|
+| `vc.meeting.participant_meeting_started_v1` | A meeting the current user participates in has started |
+| `vc.meeting.participant_meeting_joined_v1` | The current user has joined a meeting |
+| `vc.meeting.participant_meeting_ended_v1` | A meeting the current user participates in has ended |
+| `vc.note.generated_v1` | A note has been generated (meeting, recording, upload, etc.) |
+
+All four keys use a **Custom schema** (flat output) and carry a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer. All require `--as user`.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `vc.meeting.participant_meeting_started_v1` | `vc:meeting.meetingevent:read` | user |
+| `vc.meeting.participant_meeting_joined_v1` | `vc:meeting.meetingevent:read` | user |
+| `vc.meeting.participant_meeting_ended_v1` | `vc:meeting.meetingevent:read` | user |
+| `vc.note.generated_v1` | `vc:note:read` | user |
+
+---
+
+## Meeting participant events
+
+Covered keys:
+
+- `vc.meeting.participant_meeting_started_v1`
+- `vc.meeting.participant_meeting_joined_v1`
+- `vc.meeting.participant_meeting_ended_v1`
+
+### Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type; one of the covered meeting participant EventKeys |
+| `event_id` | string | Globally unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
+| `meeting_id` | string | Meeting ID |
+| `topic` | string | Meeting topic |
+| `meeting_no` | string | Meeting number |
+| `start_time` | string | Meeting start time in RFC3339, converted to the local timezone |
+| `calendar_event_id` | string | Calendar event ID associated with the meeting |
+| `end_time` | string | Meeting end time in RFC3339, converted to the local timezone; only present for `vc.meeting.participant_meeting_ended_v1` |
+
+### Gotchas
+
+- `start_time` / `end_time` are **not** the raw unix-seconds from OAPI — the Process hook converts them to local-timezone RFC3339. If the raw value is empty or non-numeric, the field is left empty. `end_time` is emitted only for `vc.meeting.participant_meeting_ended_v1`.
+- No detail API call is made; all fields come from the event payload itself.
+
+### Example
+
+```bash
+lark-cli event consume vc.meeting.participant_meeting_started_v1 --as user
+lark-cli event consume vc.meeting.participant_meeting_joined_v1 --as user
+lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user
+
+# Project meeting topic and end time only
+lark-cli event consume vc.meeting.participant_meeting_ended_v1 --as user \
+  --jq '{meeting: .meeting_id, topic: .topic, ended: .end_time}'
+```
+
+---
+
+## `vc.note.generated_v1`
+
+Fires when a note is generated — not just from meetings, but also from realtime recordings and local file uploads.
+
+### Output fields
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | string | Event type; always `vc.note.generated_v1` |
+| `event_id` | string | Globally unique event ID; safe for deduplication |
+| `timestamp` | string (timestamp_ms) | Event delivery time (ms timestamp string) |
+| `note_id` | string | Note ID |
+| `note_token` | string | Note document token; may be empty if detail is not yet available |
+| `verbatim_token` | string | Verbatim document token; may be empty if detail is not yet available |
+| `note_source` | object | Source metadata; only present when source is a meeting |
+| `note_source.source_type` | string | Source type; only present when source is a meeting (value: `meeting`) |
+| `note_source.source_entity_id` | string | Source entity ID (meeting ID); only present when source is a meeting |
+
+### Source type semantics
+
+| `source_type` | Trigger |
+|---|---|
+| `meeting` | Note generated from a meeting |
+
+`note_source` (and its sub-fields) are only populated when `source_type` is `meeting`. For other sources the field is absent.
+
+### Example
+
+```bash
+lark-cli event consume vc.note.generated_v1 --as user
+
+# Only notes with enriched tokens, skip incomplete ones
+lark-cli event consume vc.note.generated_v1 --as user \
+  --jq 'select(.note_token != "") | {note_id, note_token, verbatim_token}'
+
+# Filter to meeting-sourced notes only
+lark-cli event consume vc.note.generated_v1 --as user \
+  --jq 'select(.note_source.source_type == "meeting") | {note_id, meeting_id: .note_source.source_entity_id}'
+```

package/skills/lark-event/references/lark-event-whiteboard.md

@@ -0,0 +1,67 @@
+# Whiteboard Events
+
+> **Prerequisite:** Read [`../SKILL.md`](../SKILL.md) first for the `event consume` essentials (commands, subprocess contract, jq usage).
+
+## Key catalog (1)
+
+| EventKey | Purpose |
+|---|---|
+| `board.whiteboard.updated_v1` | A whiteboard has been edited |
+
+This key uses a **Native schema** (V2 envelope; output rooted at `.event`) and carries a **PreConsume hook** that auto-subscribes / unsubscribes via OAPI on first / last consumer.
+
+## Scopes & auth
+
+| EventKey | Scope | Auth |
+|---|---|---|
+| `board.whiteboard.updated_v1` | `board:whiteboard:node:read` | user, bot |
+
+Supports `--as user` or `--as bot`. The caller must have **manage** access to the target whiteboard, otherwise the subscribe OAPI returns 403 and `event consume` exits with an auth error before listening.
+
+## `board.whiteboard.updated_v1`
+
+### Per-whiteboard subscription
+
+Unlike global event keys (e.g. minutes / im), this key subscribes **per whiteboard**: `event consume` calls `POST /open-apis/board/v1/whiteboards/{whiteboard_id}/subscribe` on startup with the `whiteboard_id` you pass via `-p`. **Required parameter**: `-p whiteboard_id=<whiteboard_token>`. Missing this param fails param validation up-front with `required param "whiteboard_id" missing for EventKey board.whiteboard.updated_v1` before any subscription happens.
+
+Whiteboard token can be obtained via the docs OAPI [list document blocks](https://open.feishu.cn/document/ukTMukTMukTM/uUDN04SN0QjL1QDN/document-docx/docx-v1/document-block/list): the block whose `block_type=43` is a whiteboard, and `block.token` is the whiteboard token.
+
+### Output fields (V2 envelope; root path `.event`)
+
+| Field | Type | Description |
+|---|---|---|
+| `.event.whiteboard_id` | string (kind=whiteboard_id) | Whiteboard token |
+| `.event.operator_ids[].open_id` | string (kind=open_id) | Editor's open_id (`ou_` prefix) |
+| `.event.operator_ids[].union_id` | string (kind=union_id) | Editor's union_id |
+| `.event.operator_ids[].user_id` | string (kind=user_id) | Editor's user_id (only present when the caller's app has the user_id-related contact scope granted by the OAPI side) |
+
+`operator_ids` is an array — multi-user collaborative editing within one tick collapses into a single event with multiple entries.
+
+### Subscription lifecycle
+
+| Phase | Behavior |
+|---|---|
+| Startup | `event consume` calls `subscribe` OAPI; on success stderr emits `[event] consuming as ...`, `[event] running pre-consume setup...`, `[event] listening for events (key=board.whiteboard.updated_v1)...`, then the AI-facing ready marker `[event] ready event_key=board.whiteboard.updated_v1` |
+| Running | Edits to the whiteboard stream as NDJSON to stdout |
+| Graceful exit (Ctrl+C / SIGTERM / `--max-events` / `--timeout` / stdin EOF) | `event consume` calls `unsubscribe` OAPI |
+| `kill -9` | **Skips unsubscribe → server-side subscription leaks**, may cause `subscription already exists` or duplicate delivery on next consume. See SKILL.md "Never `kill -9`". |
+
+### Example
+
+```bash
+# Stream every edit on whiteboard <token> until Ctrl+C
+lark-cli event consume board.whiteboard.updated_v1 \
+    -p whiteboard_id=<whiteboard_token> \
+    --as user
+
+# Sample one event for payload inspection
+lark-cli event consume board.whiteboard.updated_v1 \
+    -p whiteboard_id=<whiteboard_token> \
+    --as user --max-events 1 --timeout 2m
+
+# Project to "edit summary": who edited which whiteboard
+lark-cli event consume board.whiteboard.updated_v1 \
+    -p whiteboard_id=<whiteboard_token> \
+    --as user \
+    --jq '{whiteboard: .event.whiteboard_id, editors: (.event.operator_ids | map(.open_id))}'
+```