docs: align messaging and node docs

2026-01-11 02:44:32 +00:00
parent 473f7df658
commit cfdca57551
6 changed files with 40 additions and 10 deletions
--- a/docs/cli/message.md
+++ b/docs/cli/message.md
@@ -24,7 +24,8 @@ Provider selection:
 Target formats (`--to`):
 - WhatsApp: E.164 or group JID
 - Telegram: chat id or `@username`
- Discord/Slack: `channel:<id>` or `user:<id>` (raw `channelId` is also accepted)
+- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are rejected)
+- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
 - Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
 - iMessage: handle or `chat_id:<id>`
 - MS Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
@@ -53,7 +54,7 @@ Target formats (`--to`):
  - Providers: WhatsApp/Discord/MS Teams
  - Required: `--to`, `--poll-question`, `--poll-option` (repeat)
  - Optional: `--poll-multi`, `--poll-duration-hours`, `--message`
-  - Discord only: `--poll-duration-hours`
+  - Discord only: `--poll-duration-hours`, `--message`

 - `react`
  - Providers: Discord/Slack/WhatsApp
--- a/docs/concepts/group-messages.md
+++ b/docs/concepts/group-messages.md
@@ -12,7 +12,7 @@ Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/
 ## What’s implemented (2025-12-03)
 - Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the silent token `NO_REPLY`. Defaults can be set in config (`whatsapp.groups`) and overridden per group via `/activation`. When `whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
 - Group policy: `whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`).
- Per-group sessions: session keys look like `whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
+- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
 - Context injection: last N (default 50) group messages are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`.
 - Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
 - Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
--- a/docs/nodes/index.md
+++ b/docs/nodes/index.md
@@ -55,11 +55,36 @@ clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format png
 clawdbot nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9
 ```

+### Canvas controls
+
+```bash
+clawdbot nodes canvas present --node <idOrNameOrIp> --target https://example.com
+clawdbot nodes canvas hide --node <idOrNameOrIp>
+clawdbot nodes canvas navigate https://example.com --node <idOrNameOrIp>
+clawdbot nodes canvas eval --node <idOrNameOrIp> --js "document.title"
+```
+
+Notes:
+- `canvas present` accepts URLs or local file paths (`--target`), plus optional `--x/--y/--width/--height` for positioning.
+- `canvas eval` accepts inline JS (`--js`) or a positional arg.
+
+### A2UI (Canvas)
+
+```bash
+clawdbot nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
+clawdbot nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
+clawdbot nodes canvas a2ui reset --node <idOrNameOrIp>
+```
+
+Notes:
+- Only A2UI v0.8 JSONL is supported (v0.9/createSurface is rejected).
+
 ## Photos + videos (node camera)

 Photos (`jpg`):

 ```bash
+clawdbot nodes camera list --node <idOrNameOrIp>
 clawdbot nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
 clawdbot nodes camera snap --node <idOrNameOrIp> --facing front
 ```
@@ -90,6 +115,7 @@ Notes:
 - Android will show the system screen-capture prompt before recording.
 - Screen recordings are clamped to `<= 60s`.
 - `--no-audio` disables microphone capture (supported on iOS/Android; macOS uses system capture audio).
+- Use `--screen <index>` to select a display when multiple screens are available.

 ## Location (nodes)

@@ -135,6 +161,8 @@ clawdbot nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready
 Notes:
 - `system.run` returns stdout/stderr/exit code in the payload.
 - `system.notify` respects notification permission state on the macOS app.
+- `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`.
+- `system.notify` supports `--priority <passive|active|timeSensitive>` and `--delivery <system|overlay|auto>`.

 ## Permissions map

--- a/docs/providers/slack.md
+++ b/docs/providers/slack.md
@@ -255,8 +255,8 @@ For fine-grained control, use these tags in agent responses:

 ## Sessions + routing
 - DMs share the `main` session (like WhatsApp/Telegram).
- Channels map to `slack:channel:<channelId>` sessions.
- Slash commands use `slack:slash:<userId>` sessions.
+- Channels map to `agent:<agentId>:slack:channel:<channelId>` sessions.
+- Slash commands use `agent:<agentId>:slack:slash:<userId>` sessions (prefix configurable via `slack.slashCommand.sessionPrefix`).
 - Native command registration is controlled by `commands.native`; text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
 - Full command list + config: [Slash commands](/tools/slash-commands)

--- a/docs/providers/telegram.md
+++ b/docs/providers/telegram.md
@@ -164,9 +164,7 @@ Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
 - Topic-specific configuration is available under `telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).

-Private topics (DM forum mode) also include `message_thread_id`. Clawdbot:
- Appends `:topic:<threadId>` to **DM** session keys for isolation.
- Uses the thread id for draft streaming + replies.
+Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.

 ## Access control (DMs + groups)

--- a/docs/tools/slash-commands.md
+++ b/docs/tools/slash-commands.md
@@ -27,7 +27,7 @@ Directives (`/think`, `/verbose`, `/reasoning`, `/elevated`) are parsed even whe
 ```

 - `commands.text` (default `true`) enables parsing `/...` in chat messages.
-  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage), text commands still work even if you set this to `false`.
+  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/MS Teams), text commands still work even if you set this to `false`.
 - `commands.native` (default `false`) registers native commands on Discord/Slack/Telegram.
  - `false` clears previously registered commands on Discord/Telegram at startup.
  - Slack commands are managed in the Slack app and are not removed automatically.
@@ -109,6 +109,9 @@ Notes:
 ## Surface notes

 - **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
- **Native commands** use isolated sessions: `discord:slash:<userId>`, `slack:slash:<userId>`, `telegram:slash:<userId>`.
+- **Native commands** use isolated sessions:
+  - Discord: `agent:<agentId>:discord:slash:<userId>`
+  - Slack: `agent:<agentId>:slack:slash:<userId>` (prefix configurable via `slack.slashCommand.sessionPrefix`)
+  - Telegram: `telegram:slash:<userId>` (targets the chat session via `CommandTargetSessionKey`)
 - **`/stop`** targets the active chat session so it can abort the current run.
 - **Slack:** `slack.slashCommand` is still supported for a single `/clawd`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`).