agent-messenger 2.21.0 → 2.23.0

package/skills/agent-discord/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discord
 description: Interact with Discord servers - send messages, read channels, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-discord:*)
 metadata:
   openclaw:

package/skills/agent-discordbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-discordbot
 description: Interact with Discord servers using bot tokens - send messages, read channels, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-discordbot:*)
 metadata:
   openclaw:

package/skills/agent-instagram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-instagram
 description: Interact with Instagram DMs - send messages, read conversations, manage accounts
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-instagram:*)
 metadata:
   openclaw:

package/skills/agent-kakaotalk/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-kakaotalk
 description: Interact with KakaoTalk - send messages, read chats, manage conversations
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-kakaotalk:*)
 metadata:
   openclaw:

package/skills/agent-line/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-line
 description: Interact with LINE - send messages, read chats, manage conversations
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-line:*)
 metadata:
   openclaw:

package/skills/agent-slack/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slack
 description: Interact with Slack workspaces - send messages, read channels, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-slack:*)
 metadata:
   openclaw:

package/skills/agent-slackbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-slackbot
 description: Interact with Slack workspaces using bot tokens - send messages, read channels, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-slackbot:*)
 metadata:
   openclaw:

package/skills/agent-teams/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-teams
 description: Interact with Microsoft Teams - send messages, read channels, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-teams:*)
 metadata:
   openclaw:

package/skills/agent-telegram/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegram
 description: Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-telegram:*)
 ---
 

package/skills/agent-telegrambot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-telegrambot
 description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-telegrambot:*)
 metadata:
   openclaw:

package/skills/agent-webex/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webex
 description: Interact with Cisco Webex - send messages, read spaces, manage memberships
-version: 2.21.0
+version: 2.23.0
 allowed-tools: Bash(agent-webex:*)
 metadata:
   openclaw:
@@ -16,7 +16,7 @@ metadata:
 
 # Agent Webex
 
-A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex through a simple command interface. Supports browser token extraction (zero-config, sends as you) and OAuth Device Grant flow.
+A TypeScript CLI tool that enables AI agents and humans to interact with Cisco Webex through a simple command interface. Supports browser token extraction (zero-config, sends as you), headless password login, and OAuth Device Grant flow.
 
 ## Quick Start
 
@@ -24,8 +24,12 @@ A TypeScript CLI tool that enables AI agents and humans to interact with Cisco W
 # Extract token from browser (Chrome, Edge, Arc, Brave) — messages appear as you
 agent-webex auth extract
 
-# Or: Log in via OAuth Device Grant (opens browser, messages show "via agent-messenger")
+# Or: Log in with email/password — messages appear as you (prompts when flags are omitted)
 agent-webex auth login
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
+
+# Or: Log in via OAuth Device Grant (opens browser, messages show "via agent-messenger")
+agent-webex auth oauth
 
 # Get workspace snapshot
 agent-webex snapshot
@@ -39,10 +43,11 @@ agent-webex space list
 
 ## Authentication
 
-Webex supports two authentication methods:
+Webex supports three authentication methods:
 
-1. **Browser token extraction** (recommended): Extracts your first-party token from a Chromium browser where you're logged into web.webex.com. Messages appear as you — no "via" label.
-2. **OAuth Device Grant**: Opens a browser for you to authorize. Messages show "via agent-messenger" label.
+1. **Browser token extraction** (`auth extract`, recommended): Extracts your first-party token from a Chromium browser where you're logged into web.webex.com. Messages appear as you — no "via" label.
+2. **Email/password login** (`auth login`): Exchanges Webex email/password for a first-party web token without opening a browser. Run `auth login` with no flags to be prompted, or pass `--email`/`--password-stdin` for headless use. Messages appear as you. Not supported for SSO/MFA accounts.
+3. **OAuth Device Grant** (`auth oauth`): Opens a browser for you to authorize. Messages show "via agent-messenger" label.
 
 ### Browser Token Extraction (Recommended)
 
@@ -68,15 +73,32 @@ agent-webex auth extract --browser-profile ~/work-profile --browser-profile ~/pe
 
 **When to re-extract**: Browser tokens expire. When your token expires, re-run `agent-webex auth extract` or let auto-extraction handle it (the CLI attempts extraction automatically on each run).
 
+### Email/Password Login
+
+`agent-webex auth login` logs you in with your Webex email and password. Run it with no flags in a terminal to be prompted for your email and then your password (the password is read without echoing). Use email/password login when no browser profile is available and the account does not require SSO or MFA.
+
+```bash
+# Interactive — prompts for email, then password (hidden input)
+agent-webex auth login
+
+# Headless — provide the email and pipe the password from stdin (keeps it out of shell history)
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
+
+# Provide the email only — the password is prompted securely when omitted
+agent-webex auth login --email <email>
+```
+
+This stores a refreshable first-party web token locally and supports encrypted messaging through the internal Webex API. Pass `--token <bot-or-personal-access-token>` to log in with a bot token or PAT instead.
+
 ### OAuth Device Grant (Fallback)
 
-`agent-webex auth login` starts the Device Grant flow: it displays a verification URL and user code, then opens the browser. You enter the code at the verification page and approve access. The CLI polls for the token automatically. Access and refresh tokens are stored locally, and the access token auto-refreshes via the refresh token.
+`agent-webex auth oauth` starts the Device Grant flow: it displays a verification URL and user code, then opens the browser. You enter the code at the verification page and approve access. The CLI polls for the token automatically. Access and refresh tokens are stored locally, and the access token auto-refreshes via the refresh token.
 
 Note: Messages sent via OAuth Device Grant show "via agent-messenger" because the token is associated with a third-party Webex Integration.
 
-Optionally, pass `--token <bot-token>` for bot token auth. Or pass `--client-id <id> --client-secret <secret>` to use your own Webex Integration credentials instead of the built-in ones.
+Optionally, pass `--client-id <id> --client-secret <secret>` to use your own Webex Integration credentials instead of the built-in ones.
 
-**For AI agents (non-TTY)**: `agent-webex auth login` exposes the OAuth Device Grant flow as a stateless two-call sequence — no hangs, no polling loops, no on-disk state. Just structured JSON every time.
+**For AI agents (non-TTY)**: `agent-webex auth oauth` exposes the OAuth Device Grant flow as a stateless two-call sequence — no hangs, no polling loops, no on-disk state. Just structured JSON every time.
 
 **Call 1** (no `--device-code` passed): the command requests a device code from Webex and returns immediately:
 
@@ -98,23 +120,28 @@ Show the user `verification_uri_complete` (or `verification_uri` + `user_code`)
 
 - **Success** — returns `{ "authenticated": true, "user": { ... } }`, exit 0.
 - **Still pending** — returns `{ "next_action": "still_pending", "device_code": "...", ... }`, exit 0. The user has not approved yet; confirm with them and retry with the same `--device-code` value.
-- **Expired / failed** — returns `{ "next_action": "restart", "error": "..." }`, exit 1. The device code is no longer usable; start over with another `agent-webex auth login` (no flags) to get a fresh one.
+- **Expired / failed** — returns `{ "next_action": "restart", "error": "..." }`, exit 1. The device code is no longer usable; start over with another `agent-webex auth oauth` (no flags) to get a fresh one.
 
 If you passed `--client-id` / `--client-secret` (custom Webex Integration) on Call 1, pass them again on Call 2.
 
 Alternatives that skip the Device Grant flow entirely:
 
 - `agent-webex auth login --token <bot-or-personal-access-token>` — fully unattended, no human required.
+- `agent-webex auth login --email <email> --password-stdin` — headless first-party login for non-SSO, non-MFA accounts.
 - `agent-webex auth extract` — read an existing browser session token (no auth flow at all).
 
 Env vars `AGENT_WEBEX_CLIENT_ID` / `AGENT_WEBEX_CLIENT_SECRET` can also override the built-in credentials.
 
 ```bash
-# Log in (Device Grant flow, opens browser)
+# Log in with email/password (prompts when flags are omitted)
 agent-webex auth login
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
+
+# Log in via OAuth Device Grant (opens browser)
+agent-webex auth oauth
 
-# Log in with custom Integration credentials
-agent-webex auth login --client-id <id> --client-secret <secret>
+# Log in via OAuth with custom Integration credentials
+agent-webex auth oauth --client-id <id> --client-secret <secret>
 
 # Log in with a bot token
 agent-webex auth login --token <token>
@@ -129,11 +156,12 @@ agent-webex auth logout
 ### Token Types
 
 - **Extracted (browser)**: First-party token from web.webex.com. Messages appear as you. Requires re-extraction when expired.
+- **Password**: First-party web token from headless email/password login. Messages appear as you. Not supported for SSO/MFA accounts.
 - **OAuth Device Grant**: Zero-config login. Access token auto-refreshes. Messages show "via agent-messenger".
 - **Bot Token**: Pass via `--token` flag. Never expires. Best for CI/CD.
 - **Custom Integration**: Pass `--client-id` + `--client-secret` or set env vars for your own Webex Integration.
 
-**IMPORTANT**: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser's network inspector. Always use `agent-webex auth extract` or `agent-webex auth login` for authentication.
+**IMPORTANT**: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser's network inspector. Always use `agent-webex auth extract`, `agent-webex auth login`, or `agent-webex auth oauth` for authentication.
 
 For detailed token management, see [references/authentication.md](references/authentication.md).
 
@@ -209,15 +237,19 @@ If a memorized ID returns an error (space not found, member not found), remove i
 ### Auth Commands
 
 ```bash
-# Log in (Device Grant flow, opens browser)
+# Log in with email/password (prompts when flags are omitted)
 agent-webex auth login
-
-# Log in with custom Integration credentials
-agent-webex auth login --client-id <id> --client-secret <secret>
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
 
 # Log in with a bot token
 agent-webex auth login --token <token>
 
+# Log in via OAuth Device Grant (opens browser)
+agent-webex auth oauth
+
+# Log in via OAuth with custom Integration credentials
+agent-webex auth oauth --client-id <id> --client-secret <secret>
+
 # Check auth status
 agent-webex auth status
 
@@ -341,7 +373,7 @@ All commands return consistent error format:
 Common errors:
 
 - `Not authenticated`: No valid token. Run `auth login` first
-- `Device authorization timed out`: User didn't complete verification in time. Run `auth login` again.
+- `Device authorization timed out`: User didn't complete verification in time. Run `auth oauth` again.
 - `401 Unauthorized`: Token expired or invalid. Re-run `auth login`
 - `429 Too Many Requests`: Rate limited. Wait and retry (Webex allows ~600 requests per minute)
 - `404 Not Found`: Invalid space ID, message ID, or resource
@@ -392,13 +424,33 @@ const msg = await client.sendMessage(spaces[0].id, 'Hello from SDK!')
 await client.sendMessage(spaces[0].id, '**Status**: All systems go', { markdown: true })
 ```
 
+### Real-time Events
+
+The SDK provides a real-time `WebexListener` backed by Webex Mercury WebSocket.
+
+```typescript
+import { WebexClient, WebexListener } from 'agent-messenger/webex'
+
+const client = await new WebexClient().login()
+const listener = new WebexListener(client)
+
+listener.on('message_created', (event) => {
+  console.log(`New message in ${event.roomId}: ${event.text}`)
+})
+
+listener.on('membership_created', (event) => {
+  console.log(`Membership changed in ${event.roomId}: ${event.personId}`)
+})
+
+await listener.start()
+```
+
 ### Full API Reference
 
 See the [Webex SDK documentation](https://agent-messenger.dev/docs/sdk/webex) for complete method signatures, types, schemas, and examples.
 
 ## Limitations
 
-- No real-time events / WebSocket connection
 - No file upload or download
 - No reactions / emoji support
 - No thread support
@@ -410,10 +462,12 @@ See the [Webex SDK documentation](https://agent-messenger.dev/docs/sdk/webex) fo
 
 ### Token refresh failed
 
-OAuth tokens auto-refresh, so expiration is handled automatically. If a refresh fails (revoked access, network issues), re-run:
+OAuth tokens auto-refresh, so expiration is handled automatically. If a refresh fails (revoked access, network issues), re-run the login method you used:
 
 ```bash
-agent-webex auth login
+agent-webex auth oauth     # OAuth Device Grant
+agent-webex auth login     # email/password
+agent-webex auth extract   # browser token
 ```
 
 Bot tokens never expire and don't need refreshing.

package/skills/agent-webex/references/authentication.md

@@ -2,12 +2,13 @@
 
 ## Overview
 
-agent-webex supports four authentication methods against the Webex REST API (`https://webexapis.com/v1`):
+agent-webex supports five authentication methods against the Webex REST API (`https://webexapis.com/v1`):
 
 1. **Browser Token Extraction**: Extracts your first-party token and cached encryption keys from a Chromium browser where you're logged into web.webex.com. Supports all operations including encrypted messaging via the internal API. Zero-config.
-2. **OAuth Device Grant** (recommended for messaging): Zero-config. Run `auth login`, approve in browser, done. Tokens refresh automatically. Supports all operations including sending messages (shows "via agent-messenger").
-3. **Bot Token**: Pass via `auth login --token`. Never expires. Best for CI/CD.
-4. **Personal Access Token (PAT)**: Pass via `auth login --token`. Expires in 12 hours. For quick testing.
+2. **Email/Password Login**: Run `auth login` to exchange email/password for a first-party web token without opening a browser. Prompts for email and password when omitted (the password is read without echoing), or pass `--email`/`--password-stdin` for headless use. Supports encrypted messaging via the internal API. Not supported for SSO/MFA accounts.
+3. **OAuth Device Grant** (recommended for messaging): Zero-config. Run `auth oauth`, approve in browser, done. Tokens refresh automatically. Supports all operations including sending messages (shows "via agent-messenger").
+4. **Bot Token**: Pass via `auth login --token`. Never expires. Best for CI/CD.
+5. **Personal Access Token (PAT)**: Pass via `auth login --token`. Expires in 12 hours. For quick testing.
 
 ## Token Types
 
@@ -40,11 +41,31 @@ Use `--browser-profile <path>` for agent-browser profiles, custom Chrome user da
 
 **Limitations**: Direct messages (`message dm`) require an existing conversation with the recipient. The extracted token cannot create new 1:1 conversations — start one from the Webex app first, then use the CLI.
 
+### Email/Password Login
+
+Use this when a browser profile is unavailable and the Webex account accepts direct email/password login.
+
+- **How it works**: Run `agent-webex auth login`. With no flags in a terminal, the CLI prompts for your email and then your password (read without echoing). For headless use, pass `--email <email> --password-stdin` (or `--email <email>` alone to be prompted only for the password). The CLI performs the Webex web OAuth + PKCE flow headlessly, registers a Webex device, and stores refreshable credentials.
+- **Auto-refresh**: The CLI refreshes expired access tokens using the stored web refresh token.
+- **End-to-end encryption**: Uses the internal Webex API with KMS key fetching, so messages appear as you without the "via" label.
+- **Limitations**: SSO and MFA accounts are not supported by this headless flow.
+
+```bash
+# Interactive — prompts for email, then password (hidden)
+agent-webex auth login
+
+# Headless — provide the email and pipe the password from stdin
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
+
+# Provide the email only — password is prompted securely
+agent-webex auth login --email <email>
+```
+
 ### OAuth Device Grant
 
 The fallback authentication method when browser extraction is unavailable. No credentials to copy, no developer portal setup required.
 
-- **How it works**: Run `agent-webex auth login`. The CLI requests a device code from Webex, opens your browser, and waits for you to approve. Once approved, access and refresh tokens are stored automatically.
+- **How it works**: Run `agent-webex auth oauth`. The CLI requests a device code from Webex, opens your browser, and waits for you to approve. Once approved, access and refresh tokens are stored automatically.
 - **Access token lifetime**: 14 days
 - **Refresh token lifetime**: 90 days
 - **Auto-refresh**: The CLI refreshes expired access tokens automatically using the stored refresh token. No manual intervention needed until the refresh token itself expires (90 days).
@@ -52,7 +73,7 @@ The fallback authentication method when browser extraction is unavailable. No cr
 - **Best for**: Interactive use, development, any scenario where a human can approve via browser
 
 ```bash
-agent-webex auth login
+agent-webex auth oauth
 ```
 
 The CLI ships with built-in Integration credentials so this works out of the box. You can override them with your own (see [Environment Variables](#environment-variables)).
@@ -89,11 +110,15 @@ agent-webex auth login --token "YOUR_PAT_HERE"
 # Browser extraction (recommended — messages appear as you)
 agent-webex auth extract
 
-# Device Grant (fallback — messages show "via agent-messenger")
+# Email/password login (messages appear as you; prompts when flags are omitted)
 agent-webex auth login
+printf '%s' '<password>' | agent-webex auth login --email <email> --password-stdin
+
+# Device Grant (fallback — messages show "via agent-messenger")
+agent-webex auth oauth
 
-# With custom Integration credentials
-agent-webex auth login --client-id <id> --client-secret <secret>
+# Device Grant with custom Integration credentials
+agent-webex auth oauth --client-id <id> --client-secret <secret>
 
 # Bot token
 agent-webex auth login --token <bot-token>
@@ -177,6 +202,22 @@ OAuth credentials (from Device Grant):
 }
 ```
 
+Password credentials (from `auth login --email`):
+
+```json
+{
+  "accessToken": "...",
+  "refreshToken": "...",
+  "expiresAt": 1234567890,
+  "clientId": "...",
+  "clientSecret": "...",
+  "tokenType": "password",
+  "deviceUrl": "...",
+  "userId": "...",
+  "encryptionKeys": {}
+}
+```
+
 Manual credentials (from `--token`):
 
 ```json
@@ -217,7 +258,7 @@ Browser-extracted tokens have no refresh mechanism — when they expire, re-extr
 ### OAuth Device Grant
 
 ```
-auth login -> Device code -> Browser approval -> Access token (14 days) + Refresh token (90 days)
+auth oauth -> Device code -> Browser approval -> Access token (14 days) + Refresh token (90 days)
                                                         |
                                                   Token expires
                                                         |
@@ -225,7 +266,7 @@ auth login -> Device code -> Browser approval -> Access token (14 days) + Refres
                                                         |
                                                   Refresh token expires (90 days)
                                                         |
-                                                  Re-run "auth login"
+                                                  Re-run "auth oauth"
 ```
 
 The CLI checks token expiry before each API call and refreshes automatically when needed. You won't notice this happening.
@@ -255,7 +296,7 @@ Override the built-in Integration credentials with your own:
 | `AGENT_WEBEX_CLIENT_ID` | Webex Integration client ID |
 | `AGENT_WEBEX_CLIENT_SECRET` | Webex Integration client secret |
 
-Both must be set together. When set, `auth login` (without `--token`) uses these instead of the built-in credentials.
+Both must be set together. When set, `auth oauth` uses these instead of the built-in credentials.
 
 Legacy aliases `AGENT_MESSENGER_WEBEX_CLIENT_ID` and `AGENT_MESSENGER_WEBEX_CLIENT_SECRET` are also supported.
 
@@ -273,7 +314,7 @@ agent-webex auth login
 
 Token is expired or invalid.
 
-**If using Device Grant**: The CLI auto-refreshes tokens, so this usually means the refresh token has expired (after 90 days). Run `agent-webex auth login` again.
+**If using Device Grant**: The CLI auto-refreshes tokens, so this usually means the refresh token has expired (after 90 days). Run `agent-webex auth oauth` again.
 
 **If using a PAT**: Generate a new one at https://developer.webex.com/docs/getting-started
 
@@ -293,7 +334,7 @@ The device code request was rejected. Possible causes:
 
 ### "Device authorization timed out"
 
-You didn't approve the request in the browser before the code expired. Run `auth login` again.
+You didn't approve the request in the browser before the code expired. Run `auth oauth` again.
 
 ### "Token validation failed"
 

package/skills/agent-webex/references/common-patterns.md

@@ -18,9 +18,12 @@ This guide covers typical workflows for AI agents interacting with Cisco Webex u
 # Recommended: Browser extraction (zero-config, sends as you, no "via" label)
 agent-webex auth extract
 
-# Fallback: Device Grant (zero-config, opens browser, shows "via agent-messenger")
+# Email/password login (messages appear as you; prompts when flags are omitted)
 agent-webex auth login
 
+# Fallback: Device Grant (zero-config, opens browser, shows "via agent-messenger")
+agent-webex auth oauth
+
 # With a bot token (never expires, for CI/CD)
 agent-webex auth login --token "YOUR_BOT_TOKEN_HERE"
 
@@ -628,7 +631,7 @@ done
 
 ```bash
 # Best: Device Grant (auto-refreshes, no token management)
-agent-webex auth login
+agent-webex auth oauth
 
 # Also good: bot token (never expires)
 agent-webex auth login --token "$BOT_TOKEN"

package/skills/agent-webexbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-webexbot
-description: Interact with Cisco Webex using bot tokens - send messages, read spaces, manage memberships, stream real-time events
-version: 2.21.0
+description: Interact with Cisco Webex using bot tokens - send messages, reply in threads, upload and download files, look up people, read spaces, manage memberships, stream real-time events
+version: 2.23.0
 allowed-tools: Bash(agent-webexbot:*)
 metadata:
   openclaw:
@@ -172,11 +172,21 @@ agent-webexbot message send <space-id> "Hello world"
 # Send a markdown message
 agent-webexbot message send <space-id> "**Bold** and _italic_" --markdown
 
+# Reply within a thread (parent message ID)
+agent-webexbot message send <space-id> "Threaded reply" --parent <message-id>
+agent-webexbot message reply <space-id> <parent-message-id> "Threaded reply"
+
+# List replies in a thread
+agent-webexbot message replies <space-id> <parent-message-id>
+agent-webexbot message replies <space-id> <parent-message-id> --max 20
+
 # Send a direct message by email
 agent-webexbot message dm alice@example.com "Hey, quick question"
 agent-webexbot message dm alice@example.com "**Build failed**" --markdown
 
 # List messages in a space
+# In group spaces, Webex only returns messages that mention the bot.
+# Direct-space history is returned normally.
 agent-webexbot message list <space-id>
 agent-webexbot message list <space-id> --max 50
 
@@ -199,6 +209,51 @@ agent-webexbot member list <space-id>
 agent-webexbot member list <space-id> --max 100
 ```
 
+### User Commands
+
+Search the Webex people directory and look up person details.
+
+```bash
+# Search people by email (exact) or display name (prefix)
+agent-webexbot user list --email alice@example.com
+agent-webexbot user list --display-name "Alice"
+agent-webexbot user list --display-name "Al" --max 20
+
+# Get details for a specific person
+agent-webexbot user info <person-id>
+```
+
+### File Commands
+
+Upload local files to a space and download attachments. Max file size is 100 MB; one file per message.
+
+```bash
+# Upload a local file
+agent-webexbot file upload <space-id> ./report.pdf
+agent-webexbot file upload <space-id> ./report.pdf --text "Latest report"
+agent-webexbot file upload <space-id> ./report.pdf --text "**Done**" --markdown
+
+# Upload a file as a threaded reply
+agent-webexbot file upload <space-id> ./report.pdf --parent <message-id>
+
+# Download an attachment (content URL comes from a message's "files" array)
+agent-webexbot file download <content-url-or-id>
+agent-webexbot file download <content-url-or-id> ./downloaded-report.pdf
+```
+
+### Snapshot Command
+
+Get a workspace overview for AI agents.
+
+```bash
+# Brief snapshot (bot identity + space IDs/titles)
+agent-webexbot snapshot
+
+# Full snapshot (includes space type and last activity)
+agent-webexbot snapshot --full
+agent-webexbot snapshot --full --max 50
+```
+
 ### Listen Command
 
 Stream real-time Webex events over the Mercury WebSocket. No public URL required.
@@ -226,6 +281,8 @@ Output is NDJSON — one JSON object per line:
 {"type":"message_created","payload":{"id":"Y2lz...","text":"Hello bot!","personEmail":"alice@example.com","roomId":"Y2lz..."}}
 ```
 
+Event IDs (`id`, `parentId`, `messageId`, `roomId`, `personId`, `actorId`, `mentionedPeople`) are emitted as Webex REST IDs (`ciscospark://...` base64), so they compare directly with IDs returned by other `agent-webexbot` commands (`message get`, `space list`, `user list`). The Mercury-only activity IDs `membership_created.id` and `room_created`/`room_updated.id` stay as raw UUIDs; the raw Mercury payload is preserved under `payload.raw` (except for `message_deleted`, whose Mercury event does not carry the full payload).
+
 ## Output Format
 
 ### JSON (Default)
@@ -312,9 +369,7 @@ Credentials stored in `~/.config/agent-messenger/webexbot-credentials.json` (060
 
 - Bot can only interact with spaces it has been added to
 - Bot can only edit/delete its own messages
-- No file upload or download
-- No reactions / emoji support
-- No thread support
+- No reactions / emoji support — the Webex public REST API does not expose a reactions endpoint, and reaction events are not delivered to bot webhooks
 - No message search
 - No voice/video or meeting support
 - No space management (create/delete spaces, roles)