agent-messenger 2.7.0 → 2.9.0

package/docs/content/docs/cli/slack.mdx

@@ -241,20 +241,37 @@ agent-slack file delete <file-id>
 
 ### Snapshot Command
 
-Get comprehensive workspace state for AI agents:
+Get workspace overview for AI agents (brief by default):
 
 ```bash
-# Full snapshot
+# Brief snapshot (default) — fast, minimal API calls
 agent-slack snapshot
 
-# Filtered snapshots
-agent-slack snapshot --channels-only
-agent-slack snapshot --users-only
+# Full snapshot — includes messages, users, user groups (slow, large output)
+agent-slack snapshot --full
 
-# Limit messages per channel
-agent-slack snapshot --limit 10
+# Filtered full snapshots
+agent-slack snapshot --full --channels-only
+agent-slack snapshot --full --users-only
+
+# Limit messages per channel (only with --full)
+agent-slack snapshot --full --limit 10
 ```
 
+Default returns brief JSON with:
+
+- Workspace metadata
+- Channels (id, name) — non-archived only
+- Hint for next commands
+
+With `--full`, returns comprehensive JSON with:
+
+- Workspace metadata
+- Channels (id, name, topic, purpose, is_private, is_archived)
+- Recent messages (ts, text, user, channel)
+- Users (id, name, profile)
+- User groups (id, name, handle, description, user_count, users)
+
 ### Activity Commands
 
 ```bash

package/docs/content/docs/cli/teams.mdx

@@ -209,20 +209,36 @@ agent-teams file download <file-id> <output-path>
 
 ### Snapshot Command
 
-Get comprehensive team state for AI agents:
+Get team overview for AI agents (brief by default):
 
 ```bash
-# Full snapshot (channels, members, recent messages)
+# Brief snapshot (default) — fast, minimal API calls
 agent-teams snapshot
 
-# Filtered snapshots
-agent-teams snapshot --channels-only
-agent-teams snapshot --users-only
+# Full snapshot — includes messages and members (slow, large output)
+agent-teams snapshot --full
 
-# Limit messages per channel
-agent-teams snapshot --limit 10
+# Filtered full snapshots
+agent-teams snapshot --full --channels-only
+agent-teams snapshot --full --users-only
+
+# Limit messages per channel (only with --full)
+agent-teams snapshot --full --limit 10
 ```
 
+Default returns brief JSON with:
+
+- Team metadata (id, name)
+- Channels (id, name)
+- Hint for next commands
+
+With `--full`, returns comprehensive JSON with:
+
+- Team metadata (id, name)
+- Channels (id, name, type, description)
+- Recent messages (id, content, author, timestamp)
+- Members (id, displayName, email)
+
 ## Global Options
 
 All commands support these options:
@@ -321,7 +337,7 @@ if ! agent-teams auth status | grep -q "valid"; then
 fi
 
 # 2. Get team context
-agent-teams snapshot --limit 5 > /tmp/teams-context.json
+agent-teams snapshot > /tmp/teams-context.json
 
 # 3. Send standup reminder
 agent-teams message send $STANDUP_CHANNEL "Good morning! Time for standup."

package/docs/content/docs/cli/webex.mdx

@@ -65,12 +65,12 @@ This command:
 
 ### Token Types
 
-| Type | Lifetime | Best For |
-| --- | --- | --- |
-| Browser Extraction (recommended) | Session-based (re-extract when expired) | Interactive use, sending as yourself |
-| OAuth Device Grant | 14-day access, 90-day refresh (auto-refresh) | Fallback when no browser session |
-| Bot Token | Never expires | CI/CD, long-running automation |
-| Personal Access Token (PAT) | 12 hours | Quick testing |
+| Type                             | Lifetime                                     | Best For                             |
+| -------------------------------- | -------------------------------------------- | ------------------------------------ |
+| Browser Extraction (recommended) | Session-based (re-extract when expired)      | Interactive use, sending as yourself |
+| OAuth Device Grant               | 14-day access, 90-day refresh (auto-refresh) | Fallback when no browser session     |
+| Bot Token                        | Never expires                                | CI/CD, long-running automation       |
+| Personal Access Token (PAT)      | 12 hours                                     | Quick testing                        |
 
 ### Authentication Commands
 
@@ -101,9 +101,9 @@ agent-webex auth logout
 
 Override the built-in Integration credentials with your own:
 
-| Variable | Description |
-| --- | --- |
-| `AGENT_WEBEX_CLIENT_ID` | Webex Integration client ID |
+| Variable                    | Description                     |
+| --------------------------- | ------------------------------- |
+| `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.
@@ -176,13 +176,26 @@ agent-webex member list abc123 --limit 100
 
 ### Snapshot Command
 
-Get workspace spaces overview for AI agents:
+Get workspace overview for AI agents (brief by default):
 
 ```bash
+# Brief snapshot (default) — fast, minimal output
 agent-webex snapshot
+
+# Full snapshot — includes type and lastActivity
+agent-webex snapshot --full
 ```
 
-Returns only the spaces you're a member of, with id, title, type, and lastActivity. Use `message list <space-id>` or `member list <space-id>` for details.
+Default returns brief JSON with:
+
+- Spaces (id, title) — only spaces you're a member of
+- Hint for next commands
+
+With `--full`, returns:
+
+- Spaces (id, title, type, lastActivity)
+
+For messages or members, use `message list <space-id>` or `member list <space-id>`.
 
 ## Global Options
 
@@ -194,16 +207,16 @@ All commands support these options:
 
 ## Key Differences: Webex vs Slack vs Discord vs Teams
 
-| Concept | Slack | Discord | Teams | Webex |
-| --- | --- | --- | --- | --- |
-| Server/Workspace | Workspace | Guild | Team | Organization |
-| Channel | Channel | Channel | Channel | Space |
-| Channel ID format | Alphanumeric (C01234567) | Numeric snowflake | UUID | Base64-encoded opaque ID |
-| Message ID format | Timestamp (1234567890.123456) | Numeric snowflake | UUID | Base64-encoded opaque ID |
-| Token lifetime | Long-lived | Long-lived | 60-90 minutes | 14 days (auto-refresh) |
-| API | Slack Web API | Discord API | Teams Messaging API | Webex REST API |
-| Auth method | Desktop app extraction | Desktop app extraction | Desktop app extraction | OAuth Device Grant |
-| Rate limits | Moderate | Moderate | Strict | ~600 req/min |
+| Concept           | Slack                         | Discord                | Teams                  | Webex                    |
+| ----------------- | ----------------------------- | ---------------------- | ---------------------- | ------------------------ |
+| Server/Workspace  | Workspace                     | Guild                  | Team                   | Organization             |
+| Channel           | Channel                       | Channel                | Channel                | Space                    |
+| Channel ID format | Alphanumeric (C01234567)      | Numeric snowflake      | UUID                   | Base64-encoded opaque ID |
+| Message ID format | Timestamp (1234567890.123456) | Numeric snowflake      | UUID                   | Base64-encoded opaque ID |
+| Token lifetime    | Long-lived                    | Long-lived             | 60-90 minutes          | 14 days (auto-refresh)   |
+| API               | Slack Web API                 | Discord API            | Teams Messaging API    | Webex REST API           |
+| Auth method       | Desktop app extraction        | Desktop app extraction | Desktop app extraction | OAuth Device Grant       |
+| Rate limits       | Moderate                      | Moderate               | Strict                 | ~600 req/min             |
 
 ## Troubleshooting
 

package/docs/content/docs/cli/wechatbot.mdx

@@ -25,14 +25,14 @@ agent-wechatbot message send oXXXXXXXXXXXXXXX "Hello from the CLI!"
 
 WeChat Official Account API works differently from typical messaging APIs:
 
-| Concept                  | Description                                                                      |
-| ------------------------ | -------------------------------------------------------------------------------- |
-| **Send-only**            | Cannot list or read received messages. Inbound messages require webhooks.         |
-| **Customer service messages** | Free-form text, image, and news messages within 48h of user's last interaction. |
-| **Template messages**    | Pre-approved templates can be sent at any time. Created in the WeChat admin panel. |
-| **App ID + App Secret**  | Credentials from WeChat Official Account admin panel under Development settings.  |
-| **OpenID**               | Each follower has a unique OpenID scoped to your Official Account.                |
-| **IP Whitelist**         | Your server IP must be added to the account's whitelist or API calls fail (40164). |
+| Concept                       | Description                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| **Send-only**                 | Cannot list or read received messages. Inbound messages require webhooks.          |
+| **Customer service messages** | Free-form text, image, and news messages within 48h of user's last interaction.    |
+| **Template messages**         | Pre-approved templates can be sent at any time. Created in the WeChat admin panel. |
+| **App ID + App Secret**       | Credentials from WeChat Official Account admin panel under Development settings.   |
+| **OpenID**                    | Each follower has a unique OpenID scoped to your Official Account.                 |
+| **IP Whitelist**              | Your server IP must be added to the account's whitelist or API calls fail (40164). |
 
 ## Authentication
 
@@ -130,9 +130,9 @@ agent-wechatbot user get oABCD1234 --lang en
 
 ## Global Options
 
-| Option           | Description                            |
-| ---------------- | -------------------------------------- |
-| `--pretty`       | Human-readable output instead of JSON  |
+| Option           | Description                             |
+| ---------------- | --------------------------------------- |
+| `--pretty`       | Human-readable output instead of JSON   |
 | `--account <id>` | Use a specific account for this command |
 
 ## Storage
@@ -173,6 +173,7 @@ If you get error `40164`, your server's IP is not in the Official Account's whit
 ### Token errors (40001, 42001)
 
 These indicate an expired or invalid access token. The CLI handles automatic token refresh, but if you see persistent errors:
+
 - Verify your App Secret hasn't been reset in the admin panel
 - Re-run `agent-wechatbot auth set <app-id> <app-secret>` with the current credentials
 

package/docs/content/docs/cli/whatsapp.mdx

@@ -114,6 +114,7 @@ agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --from-me
 ```
 
 The `<chat>` argument accepts:
+
 - Phone number: `+1234567890` (auto-resolved to JID)
 - Individual JID: `1234567890@s.whatsapp.net`
 - Group JID: `123456789-123345@g.us`
@@ -122,10 +123,10 @@ The `--from-me` flag on `message react` indicates the target message was sent by
 
 ## Global Options
 
-| Option           | Description                                |
-| ---------------- | ------------------------------------------ |
-| `--pretty`       | Human-readable output instead of JSON      |
-| `--account <id>` | Use a specific account for this command     |
+| Option           | Description                             |
+| ---------------- | --------------------------------------- |
+| `--pretty`       | Human-readable output instead of JSON   |
+| `--account <id>` | Use a specific account for this command |
 
 ## Storage
 

package/docs/content/docs/cli/whatsappbot.mdx

@@ -25,13 +25,13 @@ agent-whatsappbot message send 15551234567 "Hello from the CLI!"
 
 WhatsApp Business Cloud API works differently from the user-mode WhatsApp integration:
 
-| Concept              | Description                                                                 |
-| -------------------- | --------------------------------------------------------------------------- |
-| **Send-only**        | Cannot list or read received messages. Inbound messages require webhooks.    |
-| **Template messages** | Required outside the 24-hour customer service window. Must be pre-approved. |
-| **Phone Number ID**  | Your WhatsApp Business phone number's unique identifier (not the number).   |
-| **Access Token**     | Token from Meta Business Manager with `whatsapp_business_messaging` permission. |
-| **Rate limits**      | Tier 0-3: 80 msg/s. Tier 4: 1,000 msg/s. Based on business verification.   |
+| Concept               | Description                                                                     |
+| --------------------- | ------------------------------------------------------------------------------- |
+| **Send-only**         | Cannot list or read received messages. Inbound messages require webhooks.       |
+| **Template messages** | Required outside the 24-hour customer service window. Must be pre-approved.     |
+| **Phone Number ID**   | Your WhatsApp Business phone number's unique identifier (not the number).       |
+| **Access Token**      | Token from Meta Business Manager with `whatsapp_business_messaging` permission. |
+| **Rate limits**       | Tier 0-3: 80 msg/s. Tier 4: 1,000 msg/s. Based on business verification.        |
 
 ## Authentication
 
@@ -124,10 +124,10 @@ agent-whatsappbot template get order_confirmation
 
 ## Global Options
 
-| Option           | Description                                |
-| ---------------- | ------------------------------------------ |
-| `--pretty`       | Human-readable output instead of JSON      |
-| `--account <id>` | Use a specific account for this command     |
+| Option           | Description                             |
+| ---------------- | --------------------------------------- |
+| `--pretty`       | Human-readable output instead of JSON   |
+| `--account <id>` | Use a specific account for this command |
 
 ## Storage
 

package/docs/content/docs/index.mdx

@@ -33,13 +33,13 @@ No app creation. No admin approval. No waiting.
 
 ## Key Features
 
-| Feature             | Description                                                                                                                       |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| **Auto-extraction** | Pulls tokens from desktop apps automatically                                                                                      |
-| **Multi-platform**  | Slack, Discord, Microsoft Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta)                                                                          |
-| **Multi-workspace** | Switch between workspaces/servers easily                                                                                          |
-| **JSON output**     | Machine-readable by default, `--pretty` for humans                                                                                |
-| **Comprehensive**   | Messages, channels, users, reactions, files                                                                                       |
+| Feature             | Description                                                                                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auto-extraction** | Pulls tokens from desktop apps automatically                                                                                                                         |
+| **Multi-platform**  | Slack, Discord, Microsoft Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta)                                                             |
+| **Multi-workspace** | Switch between workspaces/servers easily                                                                                                                             |
+| **JSON output**     | Machine-readable by default, `--pretty` for humans                                                                                                                   |
+| **Comprehensive**   | Messages, channels, users, reactions, files                                                                                                                          |
 | **Bot support**     | [`agent-slackbot`](/docs/cli/slackbot), [`agent-discordbot`](/docs/cli/discordbot), and [`agent-channeltalkbot`](/docs/cli/channeltalkbot) for server-side and CI/CD |
 
 ## Why Not MCP?

package/docs/content/docs/meta.json

@@ -1,11 +1,3 @@
 {
-  "pages": [
-    "index",
-    "quick-start",
-    "agent-skills",
-    "tui",
-    "---",
-    "cli",
-    "sdk"
-  ]
+  "pages": ["index", "quick-start", "agent-skills", "tui", "---", "cli", "sdk"]
 }

package/docs/content/docs/sdk/channeltalk.mdx

@@ -10,11 +10,7 @@ npm install agent-messenger
 ```
 
 ```typescript
-import {
-  ChannelClient,
-  ChannelCredentialManager,
-  ChannelError,
-} from 'agent-messenger/channeltalk'
+import { ChannelClient, ChannelCredentialManager, ChannelError } from 'agent-messenger/channeltalk'
 ```
 
 ## ChannelClient
@@ -299,7 +295,10 @@ const manager = new ChannelCredentialManager()
 const creds = await manager.getCredentials()
 if (!creds) throw new Error('No credentials')
 
-const client = await new ChannelClient().login({ accountCookie: creds.account_cookie, sessionCookie: creds.session_cookie })
+const client = await new ChannelClient().login({
+  accountCookie: creds.account_cookie,
+  sessionCookie: creds.session_cookie,
+})
 const account = await client.getAccount()
 console.log(`Logged in as ${account.name} (${account.email})`)
 

package/docs/content/docs/sdk/channeltalkbot.mdx

@@ -10,11 +10,7 @@ npm install agent-messenger
 ```
 
 ```typescript
-import {
-  ChannelBotClient,
-  ChannelBotCredentialManager,
-  ChannelBotError,
-} from 'agent-messenger/channeltalkbot'
+import { ChannelBotClient, ChannelBotCredentialManager, ChannelBotError } from 'agent-messenger/channeltalkbot'
 ```
 
 ## ChannelBotClient
@@ -123,8 +119,8 @@ const file = await client.getGroupFileUrl(groupId, fileKey)
 // → { url: string }
 
 // Resolve a group by ID or @name (auto-detects format)
-const resolved = await client.resolveGroup('@engineering')  // by name
-const byId = await client.resolveGroup('abc123')            // by ID
+const resolved = await client.resolveGroup('@engineering') // by name
+const byId = await client.resolveGroup('abc123') // by ID
 // → ChannelBotGroup
 ```
 
@@ -296,7 +292,7 @@ for (const chat of chats) {
 
   if (lastMsg?.plainText?.includes('hours')) {
     const reply = ChannelBotClient.wrapTextInBlocks(
-      'Our support hours are Mon–Fri 9am–6pm KST. We\'ll get back to you shortly!'
+      "Our support hours are Mon–Fri 9am–6pm KST. We'll get back to you shortly!",
     )
     await client.sendUserChatMessage(chat.id, reply, 'Support Bot')
     await client.closeUserChat(chat.id, 'Support Bot')
@@ -317,9 +313,7 @@ const client = await new ChannelBotClient().login({ accessKey, accessSecret })
 const group = await client.resolveGroup('@engineering')
 
 // Send deployment notification
-const blocks = ChannelBotClient.wrapTextInBlocks(
-  'Deployment v2.1.0 complete — all services healthy'
-)
+const blocks = ChannelBotClient.wrapTextInBlocks('Deployment v2.1.0 complete — all services healthy')
 await client.sendGroupMessage(group.id, blocks, 'Deploy Bot')
 
 // Verify delivery
@@ -388,7 +382,7 @@ for (const chat of openChats.slice(0, 5)) {
 
   // Send acknowledgment
   const reply = ChannelBotClient.wrapTextInBlocks(
-    'Your request has been received. A team member will follow up shortly.'
+    'Your request has been received. A team member will follow up shortly.',
   )
   await client.sendUserChatMessage(chat.id, reply, 'Support Bot')
 }

package/docs/content/docs/sdk/discord.mdx

@@ -10,12 +10,7 @@ npm install agent-messenger
 ```
 
 ```typescript
-import {
-  DiscordClient,
-  DiscordCredentialManager,
-  DiscordError,
-  DiscordListener,
-} from 'agent-messenger/discord'
+import { DiscordClient, DiscordCredentialManager, DiscordError, DiscordListener } from 'agent-messenger/discord'
 ```
 
 ## DiscordClient
@@ -183,12 +178,12 @@ const limited = await client.searchMembers(serverId, 'alice', 5)
 // Search messages in a server
 const results = await client.searchMessages(serverId, 'deployment failed')
 const filtered = await client.searchMessages(serverId, 'API design', {
-  channelId: '123456789',   // limit to a specific channel
-  authorId: '987654321',    // limit to a specific author
-  has: 'file',              // 'file' | 'image' | 'video' | 'embed' | 'link' | 'sticker'
-  sortBy: 'timestamp',      // 'timestamp' | 'relevance'
-  sortOrder: 'desc',        // 'asc' | 'desc'
-  limit: 10,                // max 25
+  channelId: '123456789', // limit to a specific channel
+  authorId: '987654321', // limit to a specific author
+  has: 'file', // 'file' | 'image' | 'video' | 'embed' | 'link' | 'sticker'
+  sortBy: 'timestamp', // 'timestamp' | 'relevance'
+  sortOrder: 'desc', // 'asc' | 'desc'
+  limit: 10, // max 25
   offset: 0,
 })
 // → { results: DiscordSearchResult[], total: number }
@@ -200,8 +195,8 @@ const filtered = await client.searchMessages(serverId, 'API design', {
 // Create a thread in a channel
 const thread = await client.createThread(channelId, 'Bug Report: Login Issue')
 const configured = await client.createThread(channelId, 'Design Review', {
-  auto_archive_duration: 1440,  // minutes: 60, 1440, 4320, or 10080
-  rate_limit_per_user: 5,       // seconds between messages (slow mode)
+  auto_archive_duration: 1440, // minutes: 60, 1440, 4320, or 10080
+  rate_limit_per_user: 5, // seconds between messages (slow mode)
 })
 // → DiscordChannel (with thread_metadata)
 
@@ -236,7 +231,7 @@ listener.on('discord_event', (event) => {
 
 listener.on('error', (err) => console.error(err))
 
-await listener.start()  // connects via Gateway WebSocket
+await listener.start() // connects via Gateway WebSocket
 // listener.stop()      // clean shutdown
 ```
 
@@ -252,21 +247,22 @@ const listener = new DiscordListener(client, {
 
 ### Available Events
 
-| Event | Description |
-|-------|-------------|
-| `message_create` | New message in a channel or DM |
-| `message_update` | Message content edited |
-| `message_delete` | Message deleted |
-| `message_reaction_add` / `message_reaction_remove` | Reaction changes |
-| `guild_member_add` / `guild_member_remove` | Member joins/leaves server |
-| `typing_start` | Typing indicator |
-| `presence_update` | User online/idle/dnd/offline status |
-| `channel_create` / `channel_update` / `channel_delete` | Channel lifecycle |
-| `discord_event` | Catch-all for every Gateway dispatch event |
-| `connected` / `disconnected` | Connection lifecycle |
-| `error` | Connection or protocol error |
+| Event                                                  | Description                                |
+| ------------------------------------------------------ | ------------------------------------------ |
+| `message_create`                                       | New message in a channel or DM             |
+| `message_update`                                       | Message content edited                     |
+| `message_delete`                                       | Message deleted                            |
+| `message_reaction_add` / `message_reaction_remove`     | Reaction changes                           |
+| `guild_member_add` / `guild_member_remove`             | Member joins/leaves server                 |
+| `typing_start`                                         | Typing indicator                           |
+| `presence_update`                                      | User online/idle/dnd/offline status        |
+| `channel_create` / `channel_update` / `channel_delete` | Channel lifecycle                          |
+| `discord_event`                                        | Catch-all for every Gateway dispatch event |
+| `connected` / `disconnected`                           | Connection lifecycle                       |
+| `error`                                                | Connection or protocol error               |
 
 Features:
+
 - Gateway intents configurable (non-privileged defaults — `MessageContent`, `GuildMembers`, `GuildPresences` require opt-in)
 - Auto-reconnect with exponential backoff
 - Heartbeat keepalive with zombie connection detection
@@ -422,21 +418,21 @@ const thread = await client.createThread(channelId, 'Project Alpha — Kickoff',
 })
 
 // Post welcome message in the thread
-await client.sendMessage(thread.id, [
-  '👋 Welcome to **Project Alpha**!',
-  '',
-  '📋 **Resources** — links and docs will be pinned here',
-  '🧵 **Discussions** — use threads to keep things organized',
-  '🚀 **Goal** — ship the MVP by end of Q1',
-].join('\n'))
+await client.sendMessage(
+  thread.id,
+  [
+    '👋 Welcome to **Project Alpha**!',
+    '',
+    '📋 **Resources** — links and docs will be pinned here',
+    '🧵 **Discussions** — use threads to keep things organized',
+    '🚀 **Goal** — ship the MVP by end of Q1',
+  ].join('\n'),
+)
 
 // Look up team members and notify them
 const members = await client.searchMembers(serverId, 'alice')
 for (const member of members.slice(0, 3)) {
-  await client.sendMessage(
-    thread.id,
-    `Hey <@${member.user.id}>, you're on the Alpha team — see you here!`,
-  )
+  await client.sendMessage(thread.id, `Hey <@${member.user.id}>, you're on the Alpha team — see you here!`)
 }
 ```
 
@@ -457,10 +453,7 @@ for (const mention of mentions) {
   await client.addReaction(mention.channel_id, mention.id, '👀')
 
   // Reply with acknowledgment
-  await client.sendMessage(
-    mention.channel_id,
-    `Thanks for the ping <@${mention.author.id}> — on it!`,
-  )
+  await client.sendMessage(mention.channel_id, `Thanks for the ping <@${mention.author.id}> — on it!`)
 
   // Set a note on the user for context
   const existing = await client.getUserNote(mention.author.id)

package/docs/content/docs/sdk/instagram.mdx

@@ -147,12 +147,12 @@ await listener.start()
 
 ### Events
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `message` | `InstagramMessageSummary` | New message received |
-| `connected` | `{ userId: string }` | Initial poll completed, listener active |
-| `disconnected` | — | Listener stopped |
-| `error` | `Error` | Network or API error |
+| Event          | Payload                   | Description                             |
+| -------------- | ------------------------- | --------------------------------------- |
+| `message`      | `InstagramMessageSummary` | New message received                    |
+| `connected`    | `{ userId: string }`      | Initial poll completed, listener active |
+| `disconnected` | —                         | Listener stopped                        |
+| `error`        | `Error`                   | Network or API error                    |
 
 The listener seeds its seen-message set on startup, so it only emits `message` events for messages that arrive after `start()`.
 
@@ -227,8 +227,8 @@ import type {
 
 ```typescript
 interface InstagramChatSummary {
-  id: string             // Thread ID
-  name: string           // Thread title or participant names
+  id: string // Thread ID
+  name: string // Thread title or participant names
   type: 'private' | 'group'
   is_group: boolean
   participant_count: number
@@ -237,13 +237,13 @@ interface InstagramChatSummary {
 }
 
 interface InstagramMessageSummary {
-  id: string             // Message item ID
+  id: string // Message item ID
   thread_id: string
-  from: string           // User pk (numeric ID)
+  from: string // User pk (numeric ID)
   from_name?: string
-  timestamp: string      // ISO 8601
+  timestamp: string // ISO 8601
   is_outgoing: boolean
-  type: string           // 'text', 'media', 'reel_share', 'link', 'like', etc.
+  type: string // 'text', 'media', 'reel_share', 'link', 'like', etc.
   text?: string
   media_url?: string
 }
@@ -253,10 +253,10 @@ interface InstagramMessageSummary {
 
 ```typescript
 import {
-  createAccountId,      // Normalize a username to an account ID
-  getMessageType,       // Extract message type from API item
-  extractMessageText,   // Extract text from any message type
-  extractMediaUrl,      // Extract media URL from any message type
+  createAccountId, // Normalize a username to an account ID
+  getMessageType, // Extract message type from API item
+  extractMessageText, // Extract text from any message type
+  extractMediaUrl, // Extract media URL from any message type
 } from 'agent-messenger/instagram'
 ```
 
@@ -272,7 +272,7 @@ import { InstagramClient } from 'agent-messenger/instagram'
 const client = await new InstagramClient().login()
 
 const chats = await client.listChats(50)
-const unread = chats.filter(c => c.unread_count > 0)
+const unread = chats.filter((c) => c.unread_count > 0)
 
 console.log(`${unread.length} threads with unread messages:`)
 for (const chat of unread) {
@@ -294,7 +294,7 @@ const client = await new InstagramClient().login()
 
 // Find the user
 const users = await client.searchUsers('alice_smith')
-const alice = users.find(u => u.username === 'alice_smith')
+const alice = users.find((u) => u.username === 'alice_smith')
 
 if (alice) {
   const msg = await client.sendMessageToUser(alice.pk, 'Hey! Wanted to follow up on our chat.')