sipeed · github-actions · May 1, 2026
diff --git a/.doc-source.json b/.doc-source.json
diff --git a/docs/channels/index.md b/docs/channels/index.md
@@ -30,6 +30,7 @@ picoclaw gateway
 | **MaixCam** | Easy | Hardware-integrated AI camera. |
 | **VK** | Easy | VKontakte community bot via Long Poll API. |
 | **Pico** | Easy | Native WebSocket channel for custom clients. |
+| **IRC** | Medium | IRC client connection with TLS, SASL, joins, and optional IRCv3 typing tags. |
 
 ## How It Works
 
@@ -64,6 +65,7 @@ All channels support these optional fields:
 | --- | --- |
 | `reasoning_channel_id` | Route reasoning/thinking output to a separate channel |
 | `group_trigger` | Control bot behavior in group chats (mention-only, prefixes) |
+| `typing` | Enable typing indicators on channels that support them |
 
 ## Shared Gateway
 

diff --git a/docs/channels/irc.md b/docs/channels/irc.md
@@ -0,0 +1,68 @@
+---
+id: irc
+title: IRC
+---
+
+# IRC
+
+The IRC channel connects PicoClaw to IRC networks through a normal IRC client connection. It supports TLS, password/SASL authentication, channel joins, group triggers, and optional IRCv3 typing tags when the server advertises `message-tags`.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#mychannel"],
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "typing": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
+Run the gateway after saving the config:
+
+```bash
+picoclaw gateway
+```
+
+## Configuration Reference
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | bool | `false` | Enable the IRC channel |
+| `server` | string | `irc.libera.chat:6697` | IRC server and port |
+| `tls` | bool | `true` | Connect with TLS |
+| `nick` | string | `mybot` | Bot nickname. Required. |
+| `user` | string | `nick` | IRC username. Falls back to `nick` when empty. |
+| `real_name` | string | `nick` | IRC real name. Falls back to `nick` when empty. |
+| `password` | string | `""` | Server password, if required |
+| `nickserv_password` | string | `""` | NickServ password field stored in secure config |
+| `sasl_user` | string | `""` | SASL username. SASL takes priority over NickServ when configured. |
+| `sasl_password` | string | `""` | SASL password kept in secure config |
+| `channels` | string[] | `["#mychannel"]` | Channels to join after connecting |
+| `request_caps` | string[] | `["server-time", "message-tags"]` | IRCv3 capabilities to request |
+| `allow_from` | array | `[]` | Allowed IRC nicks or user IDs. Empty array allows all users. |
+| `group_trigger` | object | `{ "mention_only": true }` | Require mentions or prefixes in channel messages |
+| `typing.enabled` | bool | `false` | Send IRCv3 `+typing` tags when supported by the server |
+| `reasoning_channel_id` | string | `""` | Route reasoning output to a separate target |
+
+## Authentication
+
+Use `sasl_user` and `sasl_password` for networks that support SASL. If SASL is not configured, you can provide `password` for server authentication. `nickserv_password` is stored as secure channel configuration, but the current IRC connector does not send NickServ commands automatically.
+
+Sensitive values can be stored in `.security.yml` instead of `config.json`.
+
+## Behavior Notes
+
+IRC is line-oriented, so PicoClaw sends multi-line responses as separate IRC messages. The channel uses a conservative message length limit to fit common IRC server limits.
diff --git a/docs/channels/pico.md b/docs/channels/pico.md
@@ -0,0 +1,87 @@
+---
+id: pico
+title: Pico Protocol
+---
+
+# Pico Protocol
+
+The Pico channel is PicoClaw's native WebSocket protocol for custom clients and the web UI. It supports live messages, message edits/deletes, typing indicators, placeholders, media delivery, and tool feedback updates.
+
+PicoClaw can run either as the WebSocket server (`pico`) or as a client that connects to a remote Pico server (`pico_client`).
+
+## Server Mode
+
+Enable `pico` when this gateway should accept WebSocket clients.
+
+```json
+{
+  "channels": {
+    "pico": {
+      "enabled": true,
+      "token": "YOUR_PICO_TOKEN",
+      "allow_token_query": false,
+      "allow_origins": ["https://docs.picoclaw.io"],
+      "ping_interval": 30,
+      "read_timeout": 60,
+      "max_connections": 100,
+      "allow_from": []
+    }
+  },
+  "gateway": {
+    "host": "localhost",
+    "port": 18790
+  }
+}
+```
+
+Clients connect to the shared gateway at `/pico/ws`. Authentication uses the configured token. Query-string token authentication is disabled unless `allow_token_query` is set to `true`.
+
+## Client Mode
+
+Enable `pico_client` when this PicoClaw instance should connect outward to another Pico server.
+
+```json
+{
+  "channels": {
+    "pico_client": {
+      "enabled": true,
+      "url": "wss://remote-pico-server/pico/ws",
+      "token": "YOUR_PICO_TOKEN",
+      "session_id": "",
+      "ping_interval": 30,
+      "read_timeout": 60,
+      "allow_from": []
+    }
+  }
+}
+```
+
+## Server Configuration Reference
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | bool | `false` | Enable Pico server mode |
+| `token` | string | required | Shared token for client authentication |
+| `allow_token_query` | bool | `false` | Allow token authentication through a query parameter |
+| `allow_origins` | string[] | `[]` | Allowed browser origins. Empty array allows all origins. |
+| `ping_interval` | int | `30` | WebSocket ping interval in seconds |
+| `read_timeout` | int | `60` | WebSocket read timeout in seconds |
+| `write_timeout` | int | `0` | Optional WebSocket write timeout in seconds |
+| `max_connections` | int | `100` | Maximum active WebSocket connections |
+| `allow_from` | array | `[]` | Allowed Pico session senders. Empty array allows all users. |
+
+## Client Configuration Reference
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | bool | `false` | Enable Pico client mode |
+| `url` | string | required | Remote Pico WebSocket URL |
+| `token` | string | required | Shared token for remote server authentication |
+| `session_id` | string | `""` | Optional fixed session ID |
+| `ping_interval` | int | `30` | WebSocket ping interval in seconds |
+| `read_timeout` | int | `60` | WebSocket read timeout in seconds |
+| `allow_from` | array | `[]` | Allowed inbound session senders |
+
+## Security Notes
+
+Keep `token` in `.security.yml` for production deployments. If browser clients are used, configure `allow_origins` to the exact trusted origins instead of leaving it open.