docs: expand directory CLI guide

docs/cli/directory.md

@@ -10,12 +10,32 @@ read_when:
 Directory lookups for channels that support it (contacts/peers, groups, and “me”).
 
 ## Common flags
-- `--channel <name>`: channel id/alias (auto when exactly one channel is configured)
+- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
 - `--account <id>`: account id (default: channel default)
 - `--json`: output JSON
 
 ## Notes
-- For many channels, `directory` lists IDs from your configuration (allowlists / configured groups), not a live provider directory.
+- `directory` is meant to help you find IDs you can paste into other commands (especially `clawdbot message send --to ...`).
+- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
+- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
+
+## Using results with `message send`
+
+```bash
+clawdbot directory peers list --channel slack --query "U0"
+clawdbot message send --channel slack --to user:U012ABCDEF --message "hello"
+```
+
+## ID formats (by channel)
+
+- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
+- Telegram: `@username` or numeric chat id; groups are numeric ids
+- Slack: `user:U…` and `channel:C…`
+- Discord: `user:<id>` and `channel:<id>`
+- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
+- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
+- Zalo (plugin): user id (Bot API)
+- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
 
 ## Self (“me”)