diff --git a/main/channels/feishu/README.md b/main/channels/feishu/README.md
new file mode 100644
index 0000000..fa95018
--- /dev/null
+++ b/main/channels/feishu/README.md
@@ -0,0 +1,85 @@
+# Feishu/Lark Bot Integration
+
+This directory contains the Feishu bot integration for MimiClaw.
+
+## Features
+
+- Send text messages to Feishu chats
+- Receive messages via webhook (HTTP event subscription)
+- Automatic message chunking (4096 chars per message)
+- Tenant access token management with auto-refresh
+- Message deduplication
+- Reply to specific messages
+- Support for both DM (p2p) and group chats
+
+## Configuration
+
+### Option 1: Build-time Configuration
+
+1. Copy the secrets template:
+```bash
+cp main/mimi_secrets.h.example main/mimi_secrets.h
+```
+
+2. Edit `main/mimi_secrets.h`:
+```c
+#define MIMI_SECRET_FEISHU_APP_ID     "cli_xxxxxxxxxxxxxx"
+#define MIMI_SECRET_FEISHU_APP_SECRET "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+3. Rebuild:
+```bash
+idf.py fullclean && idf.py build
+```
+
+### Option 2: Runtime Configuration (CLI)
+
+```
+mimi> set_feishu_creds cli_xxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+## Feishu App Setup
+
+1. Go to [Feishu Open Platform](https://open.feishu.cn/)
+2. Create an app and get **App ID** / **App Secret**
+3. Enable permissions:
+   - `im:message` - Send and receive messages
+   - `im:message:send_as_bot` - Send messages as bot
+4. Configure Event Subscription:
+   - Request URL: `http://<ESP32_IP>:18790/feishu/events`
+   - Subscribe to: `im.message.receive_v1`
+5. The ESP32 will auto-respond to the URL verification challenge
+
+## Architecture
+
+```
+Feishu Server
+    |
+    v  (HTTP POST /feishu/events)
+[ESP32 Webhook Server :18790]
+    |
+    v  (message_bus_push_inbound)
+[Message Bus] --> [Agent Loop] --> [Message Bus]
+    |                                    |
+    v  (outbound dispatch)               |
+[feishu_send_message] <-----------------+
+    |
+    v  (POST /im/v1/messages)
+Feishu API
+```
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `feishu_bot_init()` | Load credentials from NVS/build-time |
+| `feishu_bot_start()` | Start webhook HTTP server |
+| `feishu_send_message(chat_id, text)` | Send text message |
+| `feishu_reply_message(message_id, text)` | Reply to a specific message |
+| `feishu_set_credentials(app_id, secret)` | Save credentials to NVS |
+
+## References
+
+- [Feishu Open Platform Docs](https://open.feishu.cn/document/home/index)
+- [Message API](https://open.feishu.cn/document/server-docs/im-v1/message/create)
+- [Event Subscription](https://open.feishu.cn/document/server-docs/event-subscription/event-subscription-guide)