docs: add serve command docs, serve_bot example, --profile usage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: DevRohit06

README.md

@@ -41,15 +41,13 @@ graph TD
 
 ```mermaid
 graph LR
-    A[discli listen --json] --> B[Events\nJSONL stream]
-    B --> C[AI Agent\ne.g. Claude]
-    C --> D[discli message reply]
-    D --> E[Discord]
-    A --> E
+    A[discli serve] -->|stdout JSONL| B[AI Agent\ne.g. Claude]
+    B -->|stdin JSONL| A
+    A <-->|persistent| C[Discord Bot API]
 
     style A fill:#5865F2,color:#fff
-    style C fill:#D97706,color:#fff
-    style E fill:#5865F2,color:#fff
+    style B fill:#D97706,color:#fff
+    style C fill:#5865F2,color:#fff
 ```
 
 ```mermaid
@@ -229,6 +227,49 @@ discli --json listen --events messages
 
 Supported event types: `messages`, `reactions`, `members`, `edits`, `deletes`
 
+### Persistent Bot (serve)
+
+`discli serve` keeps a persistent connection and communicates via stdin/stdout JSONL — ideal for building full Discord bots.
+
+```bash
+# Start with slash commands and presence
+discli serve --slash-commands commands.json --status online --activity playing --activity-text "Helping"
+
+# Filter by server
+discli serve --server "My Server"
+```
+
+**Events (stdout):**
+```json
+{"event": "ready", "bot_id": "123", "bot_name": "MyBot#1234"}
+{"event": "message", "channel_id": "456", "author": "alice", "content": "hello", "mentions_bot": true, ...}
+{"event": "slash_command", "command": "paw", "args": {"message": "hi"}, "interaction_token": "abc123", ...}
+```
+
+**Commands (stdin):**
+```json
+{"action": "send", "channel_id": "456", "content": "Hello!", "req_id": "1"}
+{"action": "reply", "channel_id": "456", "message_id": "789", "content": "Hi!", "req_id": "2"}
+{"action": "typing_start", "channel_id": "456"}
+{"action": "typing_stop", "channel_id": "456"}
+{"action": "presence", "status": "idle", "activity_type": "watching", "activity_text": "the logs"}
+```
+
+**Streaming edits** (bot response builds in real-time, edited every 1.5s):
+```json
+{"action": "stream_start", "channel_id": "456", "reply_to": "789"}
+{"action": "stream_chunk", "stream_id": "s1", "content": "new tokens..."}
+{"action": "stream_end", "stream_id": "s1"}
+```
+
+**Slash commands** are defined in a JSON file:
+```json
+[
+  {"name": "paw", "description": "Talk to the bot", "params": [{"name": "message", "type": "string"}]},
+  {"name": "new", "description": "Start a new session"}
+]
+```
+
 ## Security & Permissions
 
 ### Confirmation Prompts
@@ -251,11 +292,15 @@ Restrict which commands an agent can use:
 # List available profiles
 discli permission profiles
 
-# Set a profile
+# Set a profile (persisted)
 discli permission set chat        # Messages, reactions, threads only, no moderation
 discli permission set readonly    # Can only read, no sending or deleting
 discli permission set moderation  # Full access including kick/ban
 discli permission set full        # Everything (default)
+
+# Override per invocation (not persisted)
+discli --profile chat message send #general "hello"
+DISCLI_PROFILE=readonly discli message list #general
 ```
 
 | Profile | Can Send | Can Delete | Can Kick/Ban | Can Manage Channels |
@@ -334,6 +379,7 @@ Ready-to-run examples in the [`examples/`](examples/) directory:
 
 | Example | Description |
 |---------|-------------|
+| [`serve_bot.py`](examples/serve_bot.py) | Full bot using `discli serve` with streaming responses and slash commands |
 | [`claude_agent.py`](examples/claude_agent.py) | AI support agent powered by Claude Agent SDK with persistent session |
 | [`support_agent.py`](examples/support_agent.py) | Keyword-based support bot that replies to @mentions |
 | [`thread_support_agent.py`](examples/thread_support_agent.py) | Creates a thread per support request and continues conversations inside |
@@ -379,7 +425,7 @@ discli/
 │   ├── config.py        # Token storage (~/.discli/config.json)
 │   ├── security.py      # Permissions, audit logging, rate limiting
 │   ├── utils.py         # Output formatting, resolvers
-│   └── commands/        # Command groups (message, channel, role, etc.)
+│   └── commands/        # Command groups (message, channel, serve, etc.)
 ├── agents/
 │   └── discord-agent.md # Full command reference for AI agents
 ├── examples/            # Ready-to-run agent examples

agents/discord-agent.md

@@ -86,6 +86,15 @@ discli listen --events messages,reactions,members,edits,deletes
 discli listen --server "server name" --channel "#channel"
 ```
 
+### Persistent Bot (serve)
+`discli serve` stays connected and uses stdin/stdout JSONL for bidirectional communication.
+```bash
+discli serve --slash-commands commands.json --status online
+```
+**stdin commands:** `send`, `reply`, `edit`, `delete`, `typing_start`, `typing_stop`, `presence`, `reaction_add`, `reaction_remove`, `stream_start`, `stream_chunk`, `stream_end`, `interaction_followup`
+
+**stdout events:** `ready`, `message`, `slash_command`, `message_edit`, `message_delete`, `reaction_add`, `reaction_remove`, `member_join`, `member_remove`, `response`, `error`
+
 ## Important Rules
 
 ### JSON Output

examples/serve_bot.py

@@ -0,0 +1,133 @@
+"""
+Echo bot using discli serve.
+
+Demonstrates the bidirectional JSONL protocol: reads events from stdout,
+sends commands via stdin, and uses streaming edits for responses.
+
+Requirements:
+    pip install discord-cli-agent
+
+Usage:
+    discli config set token YOUR_BOT_TOKEN
+    python examples/serve_bot.py
+"""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+SLASH_COMMANDS = [
+    {"name": "echo", "description": "Echo your message back",
+     "params": [{"name": "message", "type": "string", "description": "Text to echo"}]},
+    {"name": "ping", "description": "Check if the bot is alive"},
+]
+
+
+async def main():
+    # Write slash commands to temp file
+    import tempfile
+    slash_file = tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False)
+    json.dump(SLASH_COMMANDS, slash_file)
+    slash_file.close()
+
+    # Start discli serve
+    proc = await asyncio.create_subprocess_exec(
+        "discli", "--json", "serve",
+        "--slash-commands", slash_file.name,
+        "--status", "online",
+        "--activity", "listening",
+        "--activity-text", "your messages",
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    req_counter = 0
+
+    async def send_cmd(action: str, **kwargs) -> None:
+        nonlocal req_counter
+        req_counter += 1
+        cmd = {"action": action, "req_id": str(req_counter), **kwargs}
+        proc.stdin.write((json.dumps(cmd) + "\n").encode())
+        await proc.stdin.drain()
+
+    async def stream_response(channel_id: str, reply_to: str, text: str) -> None:
+        """Send a response using streaming edits (simulates token-by-token)."""
+        await send_cmd("stream_start", channel_id=channel_id, reply_to=reply_to)
+        # Wait for stream_id in response
+        await asyncio.sleep(0.5)
+        # Stream word by word
+        words = text.split()
+        for i, word in enumerate(words):
+            chunk = word if i == 0 else " " + word
+            await send_cmd("stream_chunk", stream_id=stream_response.last_stream_id, content=chunk)
+            await asyncio.sleep(0.1)  # Simulate thinking
+        await send_cmd("stream_end", stream_id=stream_response.last_stream_id)
+
+    stream_response.last_stream_id = None
+
+    print("Starting serve bot...")
+
+    try:
+        while True:
+            line = await proc.stdout.readline()
+            if not line:
+                break
+
+            data = json.loads(line.decode().strip())
+            event = data.get("event")
+
+            if event == "ready":
+                print(f"Bot connected as {data['bot_name']}")
+
+            elif event == "response":
+                # Track stream IDs from responses
+                if "stream_id" in data:
+                    stream_response.last_stream_id = data["stream_id"]
+
+            elif event == "message":
+                # Skip bot's own messages
+                if data.get("is_bot"):
+                    continue
+
+                content = data["content"]
+                channel_id = data["channel_id"]
+                message_id = data["message_id"]
+                author = data["author"]
+
+                if data.get("mentions_bot"):
+                    print(f"[{author}] {content}")
+                    # Show typing, then reply
+                    await send_cmd("typing_start", channel_id=channel_id)
+                    await asyncio.sleep(1)
+                    await send_cmd("typing_stop", channel_id=channel_id)
+                    await send_cmd("reply",
+                                   channel_id=channel_id,
+                                   message_id=message_id,
+                                   content=f"You said: {content}")
+
+            elif event == "slash_command":
+                command = data["command"]
+                interaction_token = data["interaction_token"]
+                print(f"Slash command: /{command} from {data['user']}")
+
+                if command == "echo":
+                    msg = data["args"].get("message", "(empty)")
+                    await send_cmd("interaction_followup",
+                                   interaction_token=interaction_token,
+                                   content=f"Echo: {msg}")
+                elif command == "ping":
+                    await send_cmd("interaction_followup",
+                                   interaction_token=interaction_token,
+                                   content="Pong!")
+
+    except KeyboardInterrupt:
+        print("\nShutting down...")
+    finally:
+        proc.terminate()
+        Path(slash_file.name).unlink(missing_ok=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())