Merge pull request #16 from DevRohit06/docs/full-update

docs: comprehensive update for all new features + Node 22

Author: DevRohit06

.github/workflows/docs.yml

@@ -24,7 +24,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Build docs with Lito
         run: npx @litodocs/cli build -i ./docs -o ./docs/dist

docs/architecture/serve-protocol.mdx

@@ -64,6 +64,21 @@ Events are emitted by discli as things happen on Discord. Every event object has
 | Event | Fields | Description |
 |---|---|---|
 | `slash_command` | `command`, `args`, `user`, `user_id`, `channel_id`, `guild_id`, `interaction_token`, `is_admin` | Slash command invoked by a user |
+| `component_interaction` | `custom_id`, `component_type`, `values`, `user`, `user_id`, `channel_id`, `message_id`, `interaction_token` | Button click or select menu choice |
+| `modal_submit` | `custom_id`, `fields`, `user`, `user_id`, `channel_id`, `interaction_token` | Modal form submitted by a user |
+
+### Voice events
+
+| Event | Fields | Description |
+|---|---|---|
+| `voice_state` | `user`, `user_id`, `channel`, `channel_id`, `old_channel`, `old_channel_id`, `guild_id`, `self_mute`, `self_deaf` | User joined, left, or moved voice channels |
+
+### Connection events
+
+| Event | Fields | Description |
+|---|---|---|
+| `disconnected` | `code`, `reason` | Bot disconnected from Discord gateway |
+| `resumed` | -- | Bot reconnected and resumed the session |
 
 ### Reaction events
 
@@ -150,9 +165,9 @@ Actions are JSON objects sent to discli via stdin. Every action must have an `"a
 
 | Action | Required Fields | Optional Fields | Description |
 |---|---|---|---|
-| `send` | `channel_id`, `content` | `files`, `req_id` | Send a message to a channel |
-| `reply` | `channel_id`, `message_id`, `content` | `files`, `req_id` | Reply to a specific message |
-| `edit` | `channel_id`, `message_id`, `content` | `req_id` | Edit a bot message |
+| `send` | `channel_id`, `content` | `embed`, `components`, `files`, `req_id` | Send a message to a channel |
+| `reply` | `channel_id`, `message_id`, `content` | `embed`, `components`, `files`, `req_id` | Reply to a specific message |
+| `edit` | `channel_id`, `message_id`, `content` | `embed`, `components`, `req_id` | Edit a bot message |
 | `delete` | `channel_id`, `message_id` | `req_id` | Delete a message |
 
 ### Streaming
@@ -191,7 +206,10 @@ Streaming lets you progressively update a single message, similar to how ChatGPT
 
 | Action | Required Fields | Optional Fields | Description |
 |---|---|---|---|
-| `interaction_followup` | `interaction_token`, `content` | `req_id` | Send a follow-up response to a slash command |
+| `interaction_respond` | `interaction_token`, `content` | `embed`, `components`, `ephemeral`, `req_id` | Immediate response to a component interaction |
+| `interaction_edit` | `interaction_token` | `content`, `embed`, `components`, `req_id` | Edit the original interaction message |
+| `interaction_followup` | `interaction_token`, `content` | `embed`, `components`, `req_id` | Send a follow-up response to a slash command |
+| `modal_send` | `interaction_token`, `title`, `custom_id`, `fields` | `req_id` | Open a modal form in response to a component interaction |
 
 <Callout type="note">
   Slash command interactions are automatically deferred with a "thinking" indicator. You must respond with either `interaction_followup` or `stream_start` (with the `interaction_token`) within 15 minutes, per Discord's limits.
@@ -226,12 +244,18 @@ Streaming lets you progressively update a single message, similar to how ChatGPT
 | `thread_create` | `channel_id`, `name` | `message_id`, `auto_archive_duration`, `content`, `req_id` | Create a thread (optionally from a message) |
 | `thread_send` | `thread_id`, `content` | `files`, `req_id` | Send a message to a thread |
 | `thread_list` | `channel_id` | `req_id` | List threads in a channel |
+| `thread_archive` | `thread_id` | `req_id` | Archive a thread |
+| `thread_rename` | `thread_id`, `name` | `req_id` | Rename a thread |
+| `thread_add_member` | `thread_id`, `user_id` | `req_id` | Add a member to a thread |
+| `thread_remove_member` | `thread_id`, `user_id` | `req_id` | Remove a member from a thread |
 
 ### Polls
 
 | Action | Required Fields | Optional Fields | Description |
 |---|---|---|---|
 | `poll_send` | `channel_id`, `question`, `answers` | `duration_hours`, `multiple`, `content`, `req_id` | Create a poll in a channel |
+| `poll_results` | `channel_id`, `message_id` | `req_id` | Get current poll results |
+| `poll_end` | `channel_id`, `message_id` | `req_id` | End a poll early |
 
 `answers` is an array of strings or objects with `text` and optional `emoji` fields. Minimum 2 answers required.
 
@@ -242,13 +266,17 @@ Streaming lets you progressively update a single message, similar to how ChatGPT
 | `channel_list` | -- | `guild_id`, `req_id` | List channels (optionally filtered by server) |
 | `channel_create` | `guild_id`, `name` | `type`, `req_id` | Create a channel (`text`, `voice`, or `category`) |
 | `channel_info` | `channel_id` | `req_id` | Get channel details |
+| `channel_edit` | `channel_id` | `name`, `topic`, `nsfw`, `slowmode`, `req_id` | Edit channel settings |
+| `channel_set_permissions` | `channel_id`, `target_id`, `target_type` | `allow`, `deny`, `req_id` | Set permission overwrites for a role or member |
+| `forum_post` | `channel_id`, `name`, `content` | `tags`, `embed`, `req_id` | Create a post in a forum channel |
 
 ### Members
 
 | Action | Required Fields | Optional Fields | Description |
 |---|---|---|---|
 | `member_list` | `guild_id` | `limit`, `req_id` | List server members (default limit: 50) |
 | `member_info` | `guild_id`, `member_id` | `req_id` | Get detailed member info including roles |
+| `member_timeout` | `guild_id`, `member_id`, `duration` | `reason`, `req_id` | Timeout a member (max 2419200s / 28 days, 0 to remove) |
 
 ### Roles
 
@@ -257,6 +285,7 @@ Streaming lets you progressively update a single message, similar to how ChatGPT
 | `role_list` | `guild_id` | `req_id` | List server roles |
 | `role_assign` | `guild_id`, `member_id`, `role_id` | `req_id` | Assign a role to a member |
 | `role_remove` | `guild_id`, `member_id`, `role_id` | `req_id` | Remove a role from a member |
+| `role_edit` | `guild_id`, `role_id` | `name`, `color`, `permissions`, `req_id` | Edit role properties |
 
 ### DMs
 
@@ -273,6 +302,28 @@ Streaming lets you progressively update a single message, similar to how ChatGPT
 | `message_search` | `channel_id` | `query`, `author`, `limit`, `req_id` | Search messages by content or author |
 | `message_pin` | `channel_id`, `message_id` | `req_id` | Pin a message |
 | `message_unpin` | `channel_id`, `message_id` | `req_id` | Unpin a message |
+| `message_bulk_delete` | `channel_id`, `message_ids` | `req_id` | Delete multiple messages at once (2-100, max 14 days old) |
+
+### Reactions (extended)
+
+| Action | Required Fields | Optional Fields | Description |
+|---|---|---|---|
+| `reaction_users` | `channel_id`, `message_id`, `emoji` | `limit`, `req_id` | List users who reacted with a specific emoji |
+
+### Webhooks
+
+| Action | Required Fields | Optional Fields | Description |
+|---|---|---|---|
+| `webhook_list` | `channel_id` | `req_id` | List webhooks for a channel |
+| `webhook_create` | `channel_id`, `name` | `avatar`, `req_id` | Create a webhook |
+| `webhook_delete` | `webhook_id` | `req_id` | Delete a webhook |
+
+### Scheduled events
+
+| Action | Required Fields | Optional Fields | Description |
+|---|---|---|---|
+| `event_list` | `guild_id` | `req_id` | List scheduled events |
+| `event_create` | `guild_id`, `name`, `start_time` | `end_time`, `description`, `channel_id`, `location`, `req_id` | Create a scheduled event |
 
 ### Server
 
@@ -339,7 +390,11 @@ discli serve --channel "#general"
 discli serve --no-include-self
 ```
 
-Available event filter values: `messages`, `reactions`, `members`, `edits`, `deletes`.
+Available event filter values: `messages`, `reactions`, `members`, `edits`, `deletes`, `voice`, `interactions`.
+
+<Callout type="note">
+  The protocol currently supports **54 actions** and **17 event types**. See the [Serve Actions](/reference/serve-actions) and [Serve Events](/reference/serve-events) references for the complete list.
+</Callout>
 
 ## Slash command registration
 

docs/docs-config.json

@@ -51,7 +51,9 @@
           { "label": "Streaming Responses", "href": "/guides/streaming-responses" },
           { "label": "Slash Commands", "href": "/guides/slash-commands" },
           { "label": "Security & Permissions", "href": "/guides/security-permissions" },
-          { "label": "Scripting & Automation", "href": "/guides/scripting-automation" }
+          { "label": "Scripting & Automation", "href": "/guides/scripting-automation" },
+          { "label": "Components & Modals", "href": "/guides/components-modals" },
+          { "label": "AI Agent", "href": "/guides/ai-agent" }
         ]
       },
       {
@@ -61,7 +63,8 @@
           { "label": "Moderation Bot", "href": "/use-cases/moderation-bot" },
           { "label": "Thread-Based Support", "href": "/use-cases/thread-based-support" },
           { "label": "Channel Logger", "href": "/use-cases/channel-logger" },
-          { "label": "CI Notifications", "href": "/use-cases/ci-notifications" }
+          { "label": "CI Notifications", "href": "/use-cases/ci-notifications" },
+          { "label": "AI Serve Agent", "href": "/use-cases/ai-serve-agent" }
         ]
       },
       {
@@ -97,7 +100,8 @@
           { "label": "CLI Commands", "href": "/reference/cli-commands" },
           { "label": "Serve Actions", "href": "/reference/serve-actions" },
           { "label": "Serve Events", "href": "/reference/serve-events" },
-          { "label": "Permission Profiles", "href": "/reference/permission-profiles" }
+          { "label": "Permission Profiles", "href": "/reference/permission-profiles" },
+          { "label": "Component Types", "href": "/reference/component-types" }
         ]
       }
     ]

docs/guides/building-agents.mdx

@@ -794,6 +794,64 @@ if __name__ == "__main__":
 
 ---
 
+## AI Serve Agent (`ai_serve_agent.py`)
+
+Beyond the five levels above, discli ships with an example AI-powered agent that combines Claude (via the Anthropic Agent SDK) with `discli serve`. This is the recommended architecture for building intelligent Discord agents.
+
+### Architecture
+
+The AI serve agent uses a two-layer approach:
+
+1. **Claude Agent SDK** provides the reasoning and decision-making layer
+2. **`discli serve`** provides the persistent Discord connection via JSONL
+3. **Bash tool calls** let Claude execute discli CLI commands for most operations (send messages, manage channels, list members, etc.)
+4. **Component blocks** let Claude declare rich UI elements inline
+
+Claude reads events from `discli serve` stdout and decides how to respond. For standard actions, it runs CLI commands through Bash. For interactive UI elements like buttons, select menus, and modals, it uses fenced component blocks.
+
+### Component blocks
+
+The agent uses a special fenced code block syntax to declare message components:
+
+````
+```component
+{
+  "channel_id": "444555666",
+  "content": "Choose an action:",
+  "components": [
+    {
+      "type": "action_row",
+      "components": [
+        {"type": "button", "style": "primary", "label": "Approve", "custom_id": "approve"},
+        {"type": "button", "style": "danger", "label": "Reject", "custom_id": "reject"}
+      ]
+    }
+  ]
+}
+```
+````
+
+The agent framework parses these blocks and sends them as JSONL actions to `discli serve`.
+
+### Modal registry pattern
+
+Modals require a two-step flow: first you send the modal to the user (`modal_send`), then you handle their submission (`modal_submit` event). The agent maintains a modal registry that maps `custom_id` values to handler functions, so when a `modal_submit` event arrives, the agent knows which handler to invoke.
+
+### Example test messages
+
+Try these messages to exercise the agent's capabilities:
+
+- `@bot send a poll about favorite languages` -- creates a poll with buttons
+- `@bot show me server info` -- runs `discli server info` via Bash
+- `@bot create a feedback form` -- opens a modal dialog
+- `@bot set up a welcome channel` -- orchestrates channel creation and permissions
+
+### Running the example
+
+See [`agents/ai_serve_agent.py`](/agents/ai_serve_agent.py) for the full implementation. The agent requires the `anthropic` Python package and a valid `ANTHROPIC_API_KEY` environment variable.
+
+---
+
 ## Choosing Your Level
 
 <CardGroup cols={2}>

docs/guides/cli-usage.mdx

@@ -44,6 +44,14 @@ discli message send "#announcements" "New release!" \
   --embed-desc "Bug fixes and performance improvements"
 ```
 
+```bash Rich embed with color, footer, and fields
+discli message send "#announcements" "Check this out" \
+  --embed-title "Status Update" \
+  --embed-color 5865F2 \
+  --embed-footer "Last updated today" \
+  --embed-field "Service::Operational::true"
+```
+
 </CodeGroup>
 
 ## Reading Messages
@@ -164,6 +172,9 @@ discli message edit "#general" 1234567890123456 "Updated content here"
 
 # Delete a message (requires confirmation)
 discli message delete "#general" 1234567890123456
+
+# Bulk delete multiple messages by ID
+discli -y message bulk-delete "#general" 111 222 333
 ```
 
 <Callout type="warning">
@@ -196,6 +207,28 @@ discli channel create "My Server" "voice-room" --type voice
 
 # Create a category
 discli channel create "My Server" "Project Alpha" --type category
+
+# Create a forum channel
+discli channel create "My Server" "feedback" --type forum --topic "Share your feedback"
+
+# Create a forum post
+discli channel forum-post "#feedback" "Feature Request" "Add dark mode support"
+```
+</Tab>
+
+<Tab title="Edit channels">
+```bash
+# Edit a channel's topic and slowmode
+discli channel edit "#general" --topic "New topic" --slowmode 10
+```
+</Tab>
+
+<Tab title="Permissions">
+```bash
+# Set channel permissions for a role
+discli channel set-permissions "#general" "Members" \
+  --allow send_messages \
+  --deny manage_messages
 ```
 </Tab>
 
@@ -241,6 +274,12 @@ discli member ban "My Server" "@troll" --reason "Repeated violations"
 
 # Unban
 discli member unban "My Server" "@reformed"
+
+# Timeout a member for 1 hour (3600 seconds)
+discli -y member timeout "My Server" "@spammer" 3600 --reason "Spam"
+
+# Remove a timeout (set duration to 0)
+discli -y member timeout "My Server" "@spammer" 0
 ```
 
 ### The `--triggered-by` Flag
@@ -266,6 +305,9 @@ discli reaction remove "#general" 1234567890123456 "👍"
 
 # List reactions on a message
 discli reaction list "#general" 1234567890123456
+
+# List users who reacted with a specific emoji
+discli reaction users "#general" 1234567890123456 "👍"
 ```
 
 <Callout type="note">
@@ -298,6 +340,17 @@ discli thread send 9876543210 "Replying in the thread"
 
 # Send with file attachment
 discli thread send 9876543210 "Here's the file" --file ./data.json
+
+# Archive / unarchive a thread
+discli thread archive 9876543210
+discli thread unarchive 9876543210
+
+# Rename a thread
+discli thread rename 9876543210 "New Thread Name"
+
+# Add or remove a member from a thread
+discli thread add-member 9876543210 "@alice"
+discli thread remove-member 9876543210 "@alice"
 ```
 
 ## Roles
@@ -315,6 +368,13 @@ discli role assign "My Server" "@alice" "Contributor"
 # Remove a role
 discli role remove "My Server" "@alice" "Contributor"
 
+# Edit a role
+discli role edit "My Server" "Contributor" \
+  --name "Core Contributor" \
+  --color 00ff00 \
+  --hoist \
+  --mentionable
+
 # Delete a role (confirmation required)
 discli role delete "My Server" "OldRole"
 ```
@@ -337,6 +397,41 @@ discli --json server list | jq '.[] | {name, member_count}'
 ```bash
 # Create a poll (via serve mode action)
 # See the Serve Mode guide for poll_send details
+
+# View poll results
+discli poll results "#general" 1234567890123456
+
+# End a poll early
+discli poll end "#general" 1234567890123456
+```
+
+## Webhooks
+
+```bash
+# List webhooks in a channel
+discli webhook list "#general"
+
+# Create a webhook
+discli webhook create "#general" "Deploy Notifier"
+
+# Delete a webhook (requires confirmation)
+discli -y webhook delete "#general" 9876543210
+```
+
+## Scheduled Events
+
+```bash
+# List scheduled events in a server
+discli event list "My Server"
+
+# Create a scheduled event
+discli event create "My Server" "Game Night" \
+  --start "2026-04-01T20:00:00" \
+  --end "2026-04-01T23:00:00" \
+  --description "Weekly game night"
+
+# Delete a scheduled event (requires confirmation)
+discli -y event delete "My Server" 9876543210
 ```
 
 ## Permission Profiles